Skip to main content

Device credentials

Before a node can do anything useful it needs three separate pieces of information, provided at three different times by three different actors. Conflating them is the most common source of confusion in RainMaker Neo firmware work, so this page separates them.

IdentityNetwork credentialsUser association
WhatNode ID, client certificate and key, MQTT hostWi-Fi SSID + passwordThe link between this node and an end user's account
ObtainedBy claiming at first setup, or pre-flashed in manufacturingThe end user, at setupThe end user, at setup
Stored inFactory NVS (fctry)Network NVSCloud-side
Survives factory resetYesNoNo
GuideIdentity belowNetwork provisioningUser-node association

This section covers the first column — the node's identity, and how it gets created and registered. For the Wi-Fi/BLE onboarding step, see Network provisioning.

Identity​

The node's permanent identity lives in a dedicated NVS partition, conventionally called fctry. It holds the MQTT host, the X.509 client certificate and private key the node authenticates with, the node ID, and optionally a codesign certificate for OTA signature verification.

There are two ways it gets there.

Assisted claiming — the default​

The node generates its own key pair at first setup and the phone app relays a Certificate Signing Request to the claiming service over the BLE provisioning session. The service returns a certificate and a cloud-assigned node ID, which the node writes into fctry itself.

Enabled automatically whenever BLE is enabled, which is the case in every example. There is no per-device flashing step and nothing to prepare in manufacturing.

See Assisted claiming.

Pre-flashed factory NVS​

Credentials are generated by host tooling and flashed per device at manufacture. Required when you cannot claim — SoftAP provisioning, no BLE, POSIX builds — or when your factory flow needs to know node IDs up front. Opt in by setting CONFIG_ESP_RMAKER_ASSISTED_CLAIM=n.

You haveUse
Keys, certs, MQTT host, and node ID already in handfactory_nvs_gen
A handful of test nodes and a browserDashboard batch flow
A manufacturing run, or want it scriptedCLI batch flow

Registration and identity generation are two halves of one step here: the node must exist in the cloud (as an AWS IoT Thing with its certificate attached) and have matching credentials on-device. All three flows above do both. With claiming, the cloud side happens as part of the claim.

Which one​

Assisted claimingPre-flashed factory NVS
Per-device flashing stepNoneOne image per device
Node ID known before shippingNo — assigned by the cloudYes
Provisioning transportBLE onlyAny
POSIX buildsNot supportedSupported
KconfigCONFIG_ESP_RMAKER_ASSISTED_CLAIM (default with BLE)CONFIG_ESP_RMAKER_ASSISTED_CLAIM=n

Either way, the fctry partition must exist in your partition table. Claiming needs it larger (24 KB) because it writes credentials at runtime — see Partition table.

A node with no credentials cannot connect

Whichever route you choose, a node that reaches esp_rmaker_start() without a certificate will not connect — not to a wrong endpoint, not with a warning. With claiming enabled, startup fails with an explanatory error if the app never drove the exchange. With claiming disabled and nothing flashed, there is simply nothing to load. This is the most common cause of "my freshly flashed board does nothing".

Resets, and what they undo​

ResetIdentityNetwork credentialsUser association
Network resetkeptclearedkept
Factory resetkeptclearedcleared cloud-side when a new user associates
clear-claim-dataclearedkept—

So a factory-reset device is ready for a new owner: it re-advertises for provisioning and can be associated with a different account, keeping the identity it was claimed or manufactured with. See System service.

clear-claim-data is the only command that touches the identity. On a claimed node it forces a fresh claim; on a pre-flashed node it destroys credentials that can only be restored by reflashing. See Re-claiming a node.