Siot Add Node

Adding nodes to a SIOT instance

Nodes are added by writing a YAML node file and applying it, rather than by clicking through the UI. The same file format serves siot import, siot export, and provisioning, so a file that works one way works the others.

Default to siot import. It applies to a running instance immediately and is what almost every request means. Reach for the provisioning directory only when the request says provision, or asks for configuration that survives a reflash and comes up on its own.

1. Find the schema

Every client doc has a ## Schema section showing an export of that node type with its point types, value forms, and enumerations. Read it before writing anything — point types are exact strings, and a wrong one is accepted silently as a point nothing reads.

docs/user/configuration.md is the reference for the format itself.

Node types with no user doc — variable, ntp, networkManager, networkManagerConn, networkManagerDevice — take their point types from the point:"..." struct tags in the matching client/*.go. Reading an existing node of that type with siot export also works and shows real values.

2. Write the file

The node type is the key and each point type is a key under it:

nodes:
  - group:
      description: Tank farm
  - modbus:
      parent: Tank farm
      description: Sensor bus
      clientServer: client
      protocol: RTU
      port: /dev/ttyUSB0
      baud: "9600"
      pollPeriod: 500
      children:
        - modbusIo:
            description: Tank level
            id: 1
            address: 3
            modbusIoType: modbusHoldingRegister
            dataFormat: uint16
            scale: 0.1

What decides the outcome:

• How a value is written decides what it becomes. 9600 is numeric, "9600" is text. A client expecting text reads an empty value when given a number, so quote anything the schema shows quoted — port, baud, phone numbers, times.
• Descriptions are the match key. A node in a file matches an existing node when the parent and the description agree, which is what makes applying twice the same as applying once. Choose descriptions meant to last.
• Three keys are reserved: parent, children, edgePoints. Everything else is a point type, id included — on a Modbus or 1-wire node id is a device address, not the node's own ID, which never appears in a file.
• parent names a node by description and only applies to a top level entry. Entries apply in order, so a parent naming a node the same file creates has to come after it.
• A nodeID point names its target by description too, and resolves after the whole file is read, so it may point forward.
• Edge points go under edgePoints — a user's role is the one in common use.
• An entry with no description matches the single node of its type, which is how a metrics or serial node is addressed. A user has no description, so it is found by email, and by name when there is no email.
• apiVersion: 1 is optional. Adding it costs nothing and says which format the file is in.

Write files under the scratchpad directory unless they are going into the repo or a provisioning directory.

3a. Import (the default)

./siot import -dryRun < config.yaml     # prints the plan, applies nothing
./siot import < config.yaml

Read the dry run before applying. It prints one line per node — create modbus Sensor bus (7 point(s)), update ..., delete ... — so create where you expected update means the description did not match an existing node and a second node is about to appear beside it.

import reads STDIN and gives up after two seconds, so always redirect a file into it. Add -natsServer nats://127.0.0.1:4222 for an instance that is not on the default port and -token (or SIOT_AUTH_TOKEN) when it requires authentication.