ThingLab — virtual-device emulation¶
ThingLab creates repeatable virtual-device scenarios for testing TrustMint without physical hardware. Its workflow is templates → instances → rigs → emulation runs: a template says what a device is, an instance is one such device, a rig is a reusable batch of them, and a run plays the batch out.
Thing templates¶
A thing template defines the hardware identity used by virtual devices: name, manufacturer, model, firmware, device type, and thing-ID prefix. Create the template first — instances are created from it.
A template is also the object you publish and share, so it needs a sensible name before another account ever sees it.
Instances¶
An instance is one virtual device minted from a template. From the moment it exists it is a registered device, not a mock: it enrolls through the same path a factory device uses and receives a real thing ID and device certificate, so it appears in your device lists and scopes alongside hardware. What it does is simulated; what it is is not.
An instance is bound to the revision of its template that was current when it was created, so editing a template afterwards never changes what an existing instance is emulating. Delete an instance when you no longer need the device.
Sensor and software profiles¶
A sensor profile defines telemetry keys, attributes, sensor type, and the generator used to produce values.
A software profile defines applet/version identity, telemetry keys, attributes, and its generator.
Profiles are reusable. Prefer one profile per behavior so several rigs can compose the same test building blocks.
Rigs¶
A rig is a reusable batch. It selects one or more templates with a device count, attaches the sensor and software profiles those devices should emit, and sets the emission interval and the total duration.
A rig is a ThingLab object only. It carries no production meaning — sharing, grants and access are written against scopes in ThingHub, never against a rig.
Creating one device to try something out is an instance; creating a repeatable batch is a rig.
Emulation runs¶
Start a run from a saved rig. The run records its status, timing, owner, device totals, stop reason, and any error. A running emulation can be stopped from the run list.
Deleting a template, profile, instance, or rig is destructive and requires typed confirmation. Do not delete an object that an active or retained scenario still needs.
Publishing and sharing a template¶
By default a template is yours alone. Publishing and sharing are how you offer it to another account.
Publishing records which version of the template is on offer. Anything you change in the template afterwards is a new version, so publishing again offers the new one; publishing a template whose content has not changed simply re-opens the version already offered.
# Open the template's current content as the offered version
fgai simulation templates-publications --id tmpl-01
A published template is in one of three states:
State |
What it means |
|---|---|
Published |
Open. A new emulation may be started from it. |
Deprecated |
Still usable — a statement that the version is on its way out. It stops nothing that is running and it does not block a new start. |
Withdrawn |
Nobody may start a new emulation from it, including you. Emulations already running keep running. |
Withdrawal is the state to reach for when a version turns out to be wrong: withdrawing stops new work from it without killing anything in flight. Publishing again re-opens it, so neither state is a delete.
# Move one offered version to a different state
fgai simulation templates-publications-update --id tmpl-01 --publication pub-01 --body '{"state":"withdrawn"}'
Sharing names one account that may see the published template. Sharing is per account, not per organization, and it comes after publishing: an audience is a statement about what you are offering, so there must be an offering to point at.
fgai simulation templates-audiences --id tmpl-01 --body '{"audience_kind":"account","audience_id":"acc-partner-01"}'
What the other account gains is visibility, not authority. It can see the published template and start its own emulations from it; it cannot publish, deprecate, withdraw or re-share it, and it cannot read the profiles you composed it from. Those stay yours, and every operation it performs on its own devices is checked against its own account as usual.
# Who can see this template, and who could before — revoked audiences stay on the list
fgai simulation templates-audiences-get --id tmpl-01
# End one audience; access stops, the record of it does not
fgai simulation templates-audiences-delete --id tmpl-01 --audience_grant aug-01
Revoking does not erase the audience: the list keeps it with the time it ended, so “who could see this, and until when” stays answerable. Sharing the same account again afterwards records a separate, new grant.
Copying takes a template into your own account as a new template of yours:
fgai simulation templates-copy --id tmpl-01
A copy of your own template brings everything. A copy of a template shared with you brings the template’s own content, and leaves behind the composed profiles and the owner’s model binding — those are rows in the sharing account, and the platform never checked your account against the model behind them. The response names each thing it did not carry, so the copy is never quietly narrower than the source. Your copy is your own row from then on: if the owner later changes or withdraws theirs, yours is unaffected. Its provenance is recorded, so you can always see where it came from.
Limits¶
Starting a run is refused when it would exceed the deployment’s configured limits — a maximum number of concurrent runs and a maximum number of devices in one run. The refusal names the limit and the current value. These limits are configured per deployment and enforced by ThingLab itself; contact support to discuss a higher limit.
Note
ThingLab is simulation-only. It does not create real manufacturing identities or replace ThingMake provisioning.