Concepts
The four nouns
Connector, physical device, logical device, interaction, and why you integrate against the logical one.
Four things, and one relationship between two of them that is worth more than the rest of this page.
Connector
The box on the venue's network. It holds one outbound connection to the cloud, discovers the hardware around it, and does the actual talking to devices. One connector usually covers one venue.
Physical device
A real piece of hardware the connector has found or been told about: a printer at 192.168.1.50:9100, a scale on a USB port. Identified by a fingerprint the connector derives, not by anything you choose.
Logical device
The thing you integrate against: "Kitchen printer", "Deli scale". It has a stable id, it lives under a connector, and it is assigned to a physical device.
Why there are two
Because hardware dies on a Friday night. When the kitchen printer is replaced, the operator assigns the new one to the same logical device, and the id you have stored in your database keeps working. Had you integrated against the hardware, every replacement would be a data migration on your side.
This is the single most useful idea in the model: store the logical device id, never an IP address, never a fingerprint.
Interaction
One request to one device: a print job, a weigh, a bridge call. It is a durable record with a lifecycle, not a fire-and-forget, which is why a print submission hands you back an interaction id and a URL to watch it on.
Interactions are how you answer "did it work?" after the fact, and they are what the dashboard's history is made of. Their status model is on Printing a ticket.
In one sentence
A connector at the venue finds physical devices; you address a logical device bound to one of them; each request you make is an interaction you can follow to an outcome.