CLI batch flow

factory_autoreg does in one command what the dashboard flow does in three clicks — create node identities, register them with the admin API, and write factory NVS artifacts — and it is scriptable, which is what makes it the manufacturing path.

factory_attach then merges those per-device factory partitions into full flash images.

For a single node whose credentials you already have, use factory_nvs_gen instead.

Prerequisites

Set up the tools Python environment (no RainMaker Neo backend checkout needed — RMNG_BACKEND_DIR is not required for these tools). See Tools reference.

Dependency	Needed for
`boto3`, `requests`, `cryptography`, `shortuuid`	Always
`esp-idf-nvs-partition-gen` on `PATH`	ESP-IDF `.bin` output. Without it the script warns and skips IDF output.

What it does

One sign-in per run — the super admin signs in directly against the admin Cognito user pool, then fetches temporary AWS credentials for API Gateway — followed by a loop over the batch. Note that credential creation and registration are both part of the same step — unlike the dashboard flow, there is nothing to remember to do afterwards.

Configuration

Defaults to tools/common/credentials_store/general/rmng-outputs.json. Override with --config, which accepts a filesystem path or a client-outputs URL.

Source	Keys used
`rmng-base`	`ApiGatewayUrl`, `StackRegion`, `IoTEndpointUrl`, `StackAccountId`
`esp-user-base`	`EspAdminUserPoolClientId` (admin Cognito sign-in)

This is the same outputs file the stack tooling produces, so point it at your deployment's outputs rather than transcribing values.

Usage

factory_autoreg.py [-h] [--codesign-cert CODESIGN_CERT] [--config CONFIG] [-n N]
                   [--output-dir OUTPUT_DIR] [--key-type {ec,rsa}]
                   [--part-label PART_LABEL] [--namespace NAMESPACE]
                   [--thing-groups THING_GROUP [THING_GROUP ...]]
                   [--tags TAG [TAG ...]]
                   [--capabilities CAP [CAP ...]]
                   username password

Argument	Notes
`username`, `password`	Super-admin credentials. Keep them out of shell history — use environment variables or secret injection in automation.
`-n` / `--count`	Batch size. Writes `batch_summary.json` when greater than 1.
`--output-dir`	Root for outputs. Defaults to `outputs/` next to the script.
`--part-label`	Factory partition label. Default `fctry`; must match your firmware's Kconfig and `partitions.csv`.
`--namespace`	Factory NVS namespace. Default `rmaker_creds`.
`--key-type`	`ec` or `rsa` (default `ec`).
`--codesign-cert`	Codesign certificate to embed, for OTA signature verification.
`--thing-groups`, `--tags`	Passed through to registration.
`--capabilities`	Space-separated: `s3`, `kvs`, `bridge`. Each attaches the matching server-side policy at registration.

Examples

cd tools/factory_autoreg

# One node against a specific deployment
python3 factory_autoreg.py --config /path/to/rmng-outputs.json admin_user 'secret'

# A batch of five, into a chosen output directory
python3 factory_autoreg.py --config /path/to/rmng-outputs.json -n 5 --output-dir ./out admin_user 'secret'

# A bridge node — attaches the bridge capability policy
python3 factory_autoreg.py --config /path/to/rmng-outputs.json admin_user 'secret' --capabilities bridge

caution

Get --part-label and --namespace right

They must match CONFIG_ESP_RMAKER_FACTORY_PARTITION_NAME and CONFIG_ESP_RMAKER_FACTORY_NAMESPACE in the firmware you will flash. A mismatch produces a partition the firmware cannot read, and the symptom looks identical to having no partition at all.

Output layout

<output-dir>/<StackAccountId>/<thing_type>/<thing_key>/
├── factory_nvs_input.json
├── esp-idf/<part-label>.bin
├── posix/nvs_persistent/*.bin     # when NVS generation succeeded
└── registration.json

Component	Values
`thing_type`	`rmng-only`
`thing_key`	A 22-character Base62 string

Batch index: <output-dir>/<StackAccountId>/<thing_type>/batch_summary.json.

Full detail is in tools/factory_autoreg/README.md.

Merge factory data into a full flash image

factory_attach.py, in the same directory, merges generated factory partitions into ESP-IDF merged-flash binaries using the flash_args from your build directory:

factory_attach.py <build_dir> <offset> [artifacts_dir] [--truncated N] [--binaries-dir BINARIES_DIR]

Argument	Notes
`build_dir`	The ESP-IDF `build` folder containing `flash_args`
`offset`	Factory NVS partition offset, hex or decimal (e.g. `0x3E0000`). Must match `partitions.csv`.
`artifacts_dir`	Optional; defaults to `tools/factory_autoreg/outputs`
`--binaries-dir`	Where the merged `*.bin` files are written

Run without arguments beyond the essentials and it offers an interactive flow for picking the stack account, thing type, and things (including all or a range). Output names follow:

<target>-<project_name>-<thing_name>.bin

Each file is a complete flash image for one specific device — flash at 0x0. See the README section Attach factory partition to build image for the menu behaviour.

Which tool for what

	`factory_nvs_gen`	`factory_autoreg`	Dashboard
Creates keys and certs	No — you supply them	Yes	Yes
Registers with the cloud	No	Yes	Yes (separate step)
Batch	No	Yes	Yes, up to a per-batch cap
ESP-IDF `.bin`	Yes	Yes	Yes
POSIX `nvs_persistent/`	Yes	Yes	No
QR images	No	No	Yes, PNGs for every node
Scriptable	Yes	Yes	No
Needs AWS/admin credentials	No	Yes	Yes (browser sign-in)

Security

registration.json, the private keys, and the merged binaries are all per-device secrets. Never commit them; keep production outputs in secure storage; use throwaway credentials in CI. See Factory NVS → Security.

Prerequisites​

What it does​

Configuration​

Usage​

Examples​

Output layout​

Merge factory data into a full flash image​

Which tool for what​

Security​

Related​