Device support

Every registered device carries a sensor family (its deviceType), chosen once at registration. That family is the single dispatch axis for everything device-kind specific: which local transports the web offers, whether the onboarding configuration can be pushed over a direct connection, which driver speaks to the hardware, and how workbook protocol cells execute against it. Downstream code reads capability registries; it never branches on family names inline. Adding a family therefore means adding registry entries and (when the hardware speaks its own protocol) a driver, not editing consumers.

This page is the internal counterpart to Device Integration, which documents the contract from the device implementer's side.

How a device receives its configuration

The onboarding configuration file is the canonical interface, and it assumes nothing about the device beyond storage: the operator downloads the JSON and loads it however the hardware allows (flashing during provisioning, SD card, a vendor tool). Every family supports this path, and for most it is the only one.

On top of that baseline there is one optional capability, declared per family in the registry:

When push is off, the panel explains why with a per-family note: the inline-procedure families (MultispeQ, Ambit, MiniPAR) receive their procedure per measurement and have nothing to store, while Ambyte edge devices load their configuration at provisioning time and expose no onboarding commands over a direct connection. Only the generic family opts into the push today.

A device that wants push support must implement the SET_CONFIG frame documented in Device Integration, persist the delivered config, and treat each delivery as full desired state.

Where family knowledge lives

@repo/iot stays dependency-free, so SENSOR_FAMILIES is duplicated by hand from zSensorFamily rather than imported; the two lists differ deliberately when a family has no local identification handshake (Ambyte today).

Two things intentionally do not change per family:

• The backend onboarding compose is family-agnostic. The family only appears in the returned deviceType field and as the sensorType segment baked into each topicPrefix.
• The ingest infrastructure needs no change: sensorType is a parameter of the AsyncAPI channel, so topic rules and IoT policies already match any family value.

Current families

The mobile family is special: phones register themselves silently when someone signs into the mobile app (one Thing per install, Cognito-authenticated, no certificate lifecycle), so it never appears in the manual registration dialog, has no credentials or onboarding surface, and cannot be selected as a protocol family.

Adding a new family

Work through the layers top to bottom; the exhaustive types surface most omissions as compile errors.

1. Database: add the value to the sensor_family enum and generate a migration.
2. API contract: add the value to zSensorFamily, then follow the compile error into DEVICE_PROFILES with the product spelling and display roles.
3. Device toolkit (@repo/iot): add the value to the DeviceType union and give it a DEVICE_TRANSPORT_SUPPORT entry stating its transports and whether it accepts a stored config. If the hardware is identifiable over a local probe and speaks its own protocol, add a driver under packages/iot/src/driver/, list the family in SENSOR_FAMILIES, and extend createConnectorForFamily; otherwise leave it out of SENSOR_FAMILIES and route it through GenericDeviceDriver at the host.
4. Web host: add the mapping case in sensorFamilyToDeviceType, the createDriver case, and an execution branch in executeProtocolWithDriver when the generic flow does not fit. If push is off and the inline-procedure wording is wrong for the hardware, add a note key to DOWNLOAD_ONLY_NOTE_KEYS with copy in all three locales.
5. Fixtures and tests: extend the seed if the family should exist in dev data, and update the specs that pin the registries: onboarding.spec.ts in @repo/iot, and the web tests for the mapping, browser support, communication, protocol execution, and config delivery.
6. Docs: extend Device Integration when the configuration contract gains family-specific behavior.

Capability changes for an existing family follow the same path minus the enum work: flip the registry flag, adjust the host branches the compiler points at, and update the pinned specs.