Enrollment Module (ID 5)

The EnrollmentModule supports enrollments over the mesh. A normal enrollment message is sent as a broadcast through the mesh together with the nodeKey of the node that should be enrolled. All receiving nodes of this message try - at a certain random percentage - to scan for this node. They temporarily store the enrollment data and connect to the node once it is found and enroll it. Also, at a certain random percentage, the node sends an enrollment proposal through the mesh that contains some nearby serial numbers that the MeshGateway might like to enroll.

If the message is sent to a specific nodeId, this node will try to scan for the other node with a 100 percent probability. This is useful if the nodes position is already known, e.g. by parsing an enrollment proposal.

The EnrollmentModule supports PreEnrollments. A module can register itself using SetPreEnrollmentHandler. The EnrollmentModule then calls this handler when an unenrollment or enrollment is received. The module then has a fixed time to perform an enrollment of other components, e.g. an external controller. Once it is done, it must call SaveEnrollment so that the node enrollment is processed. If this is not called within a defined time, the enrollment will fail with the result code PreEnrollmentFailed.

If allowUnenrolledUnsecureConnections is set in the feature set and the node is in an unenrolled state, nodes accept connections with FM_KEY_ID_ZERO for enrollment. This allows an easier enrollment process.

Preferred network enrollment is used for assets because we would like to set their network id in order for assets to send their measurement to nodes in a particular network. In case of preferred network enrollment, the asset won’t restart. In PreferredNetwork only networkId and nodekey is given.

It is possible to activate nearby enrollment by enabling allowUnenrolledUnsecureConnections through the featureset. A node can then be enrolled using a MeshAccessConnection with the known ZeroKey. This can only be done if a node is unenrolled. This is useful if no QR code or other method is available to distribute the device key. The featureset has to provide some means of resetting the node to an unenrolled state, e.g. by pressing a button, resetting the power, etc,…​ This is necessary because the user might lose access to the Network Key and might be unable to remove the enrollment afterwards.

For most nodes and asset tags that have a user accessible button which is not directly wired to do a power cycle, it is possible to perform an unenrollment by pressing the button for a duration between 10 to 14 seconds. Afterwards, the leds will start flashing frantically for about 7 seconds to signal that the unenrollment is performed.

Most devices can also be powered off by pressing the button for a short time. Read more about this topic here.

The data stored in the UICR defines the default enrollment of a node. If a node is assigned to networkId 0 by default, it doesn’t participate in the mesh until it is enrolled. If a node is assigned another networkId and networkKey as a default, it tries to connect to the mesh after it is flashed. Resetting the node reverts the node back to its defaults.

Removing an enrollment from a node will reset all settings to default (factory reset). The node will return to its default network.

If the node is an asset, it allows rapid network id changes by using this command. A connection must have been established before executing this command, no mesh access connection is automatically created.

In some situations (e.g. when the nodes are placed in a line) it can be helpful to specifically query which node sees which serial numbers before sending the enrollment. Therefore, it is possible to send the request_proposals message with several serial numbers that are then temporarily stored on the target node. The target node will respond with a proposal message as soon as it receives a broadcast message of one of the nodes to be enrolled.

The nodes then scan for one minute if they see any of the specified serial numbers. Upon arrival, the message is answered with the following JSON (1 JSON per serial number):