Docs menu

Live Devices

Connect a real device or stream that pushes data into your workshop.

Where the device registers

A Connection is one device in an Azure IoT Hub. You do not have to bring a hub or an Azure subscription to start: until your workspace has a private landing zone and its own IoT fabric, a connection registers in Fathym's shared IoT hub. Once your workspace has provisioned its IoT fabric (Data Fabric), connections register in your own hub, in your own subscription.

Add a connection

  • Canvas: drag a Connection onto the canvas, name it, and open its Inspector.
  • Thinky or any AI: ask for it ("Create a connection called factory-sensors for my production devices") and review the proposal.

The Settings tab has two fields:

FieldWhat it does
Connection IDThe name of the connection
Is IoT Edge DeviceRegisters the device in the hub as an IoT Edge device. Leave it off for an ordinary device or sensor

The device does not exist in the hub until the connection is deployed: Deploy registers it. Switching the connection off in its Inspector and deploying disables the device in the hub; it keeps its keys but cannot send.

Get the credentials: Connection Info

Select the connection and open Inspector -> Connection Info. The tab is read from the hub each time it loads.

SectionWhat it shows
OverviewHealth and Last Received, the time the hub last heard from the device
IdentityCloud, IoTHub, HostName, DeviceID, Status (the hub's connection state, such as Connected) and AuthType (symmetricKey, or x509 for a device that uses certificates)
Device AccessDevice ConnStr (primary) and (secondary), the key-based connection strings a device keeps, and testing tokens, primary and secondary
MQTTMQTT Host, MQTT Port, MQTT Username, MQTT Password and MQTT Telemetry Topic
AMQPAMQP Host, AMQP Port, AMQP Username and AMQP Password
HTTPHTTP Endpoint and HTTP Auth (Authorization)

Each value has a copy button. A device that authenticates with a certificate shows its authentication as x509 client certificate in place of a password.

Point the device at it

The device keeps the key-based connection string. It carries the device's own key, it does not expire, and it is what goes into the device:

HostName=<hub>.azure-devices.net;DeviceId=<device id>;SharedAccessKey=<key>

Copy the whole value from Device ConnStr (primary). Use the secondary for the same device when you move it over. Given this string, an Azure IoT device SDK makes its own short-lived pass and renews it. Firmware without an SDK makes the pass from the key itself: Pilot Devices has the steps.

MQTT directly. Port 8883, TLS required:

SettingValue
HostMQTT Host
PortMQTT Port (8883)
Client IDThe DeviceID from Identity
UsernameMQTT Username
PasswordA pass the device makes from its key (how); MQTT Password is a testing token
Publish toMQTT Telemetry Topic

AMQP uses AMQP Host (port 5671) and AMQP Username, with a pass made from the key as the password; AMQP refreshes the pass without dropping the connection. HTTPS posts the message body to HTTP Endpoint, port 443, with a pass made from the key as the Authorization header: the choice to make when a firewall allows only web traffic, at the cost of more latency than MQTT. The AMQP Password and HTTP Auth (Authorization) values in Connection Info are testing tokens.

ProtocolPortUse it for
MQTT8883Most devices, lowest overhead
AMQP5671Enterprise messaging
HTTPS443Firewalls that allow only web traffic

Testing tokens

The device tokens in Connection Info (the MQTT Password, AMQP Password and HTTP Auth (Authorization) values, and the device SAS tokens under Device Access) are for testing only: each lasts seven days unless you choose a longer device token (30, 90, 180 or 365 days, for people with the right to deploy) (testing tokens), so a device that stores one stops connecting when it expires. Testing tokens are made from the inspector. Use one to try a connection from a test client, never as what a device keeps. Copy with expiry date copies a token with a line giving its expiry in UTC.

A device keeps the key-based connection string and makes its own pass from it. Pilot Devices walks through it for a run of units: one key per unit, a pass made from the key, a correct clock, and a new pass once a day.

Treat every credential here like a password: never put it in source control, a log, or client-side code. Use your IoT Hub securely says which key each thing you build should hold.

Replace a credential

A connection's device has two keys, shown as Device ConnStr (primary) and Device ConnStr (secondary). The connection's Inspector replaces one of them: Regenerate secondary key. It replaces the secondary key only, and the primary is refused.

  1. Select the connection and press Regenerate secondary key in its Inspector. A confirm says: "Regenerating the secondary key affects every device that holds this connection's secondary key: each one needs the new key string before it can send again. The primary key is unchanged, so a device on it keeps working. A device provisioned through DPS re-provisions instead."
  2. Confirm with Regenerate the secondary key. The Inspector then says "The secondary key was regenerated. The primary key is unchanged, so a device on it keeps working. Each device that used the secondary key needs the new key string."
  3. Copy the new Device ConnStr (secondary) to every device that was on the secondary key.

What it does and does not do:

  • It changes only the secondary key, in the hub's record of the device. It is not a Deploy, and it does not switch the device on or off. Pull Now and provenance forwarding pick up the new key without a Deploy.
  • It needs the Workspace.Deploy right.
  • The primary key cannot be regenerated from OpenX yet: a request for it is refused with DEVICE_KEY_PRIMARY_REFUSED, because the API Source's poller holds the primary key from the last Deploy and would stop sending. There is no button for it.
  • A device that signs in with a certificate, or that was provisioned through DPS, has no key here to replace; a device provisioned through DPS re-provisions instead.

If the exposed key is the primary one, replacing the secondary does not close it. Switch the connection off in its Inspector and Deploy to disable the device, and take the primary key up with whoever runs the hub: Fathym for the shared hub, you for your own. See Use your IoT Hub securely.

Check health

Health in Connection Info is read from the hub's record of the device, not from the messages it sent:

HealthMeaning
HealthyThe hub shows the device connected and it was heard from less than 90 seconds ago
StaleHeard from between 90 seconds and 10 minutes ago, or not connected but heard from in the last 10 minutes
UnreachableNot heard from for 10 minutes or more, or the device is not in the hub: the tab reads "Device not registered in IoT Hub"
UnknownThe hub holds no activity time for it, as for a device that is registered and has never sent

From any AI, get_stats reports the same connections' health.

Verify

Live data-flow particles on the connection and events in the Live Stream panel. No data? See Can't connect.

What you seeWhat to check
No Device Access sectionDeploy the connection first. Until the hub has the device, Connection Info reads "Device not registered in IoT Hub"
The connection string failsCopy the whole value, including the SharedAccessKey
A token is rejectedA testing token expired: a device makes its own pass from its key (how). A pass the device made is refused when its clock is behind (clock)
MQTT will not connectPort 8883 open, TLS on, the username copied from the MQTT section, and a pass made from the key as the password
UnreachableThe device has not connected for 10 minutes or more. Check the device's power, network and credentials

Then

Route it to a Surface and crystallize a Warm Query. To test before you have a device, use the Simulator.

On fathym.com: OpenX →

On this page