Devices behind a gateway

A gateway collects data from field devices that cannot reach Hermetry themselves (Modbus meters, RS485 controllers, BLE sensors and others) and sends it on its own connection. Hermetry turns each field device into a child device: a device of its own with readings, attributes, alarms and dashboards. This page is the full reference for the gateway side. For a short summary, see Gateways and devices behind a gateway.

A licensed gateway running Hermetry Edge does all of this for you; see Licensed gateways and Hermetry Edge. Read on if you write gateway software yourself or want to know what happens to the data.

Set up the gateway device

Create or choose a device profile for the gateway. It must use the default v1/ topic scheme. The Legacy compatible scheme carries no gateway API.
Under Devices > New device, add the gateway and turn on This device is a gateway. A device without it is refused on every v1/gw/* topic (forbidden_topic).
Give the gateway its credentials (access token, MQTT basic or X.509 certificate) as for any MQTT device. See Device credentials.
Optional: on the gateway’s profile, set Profile of new children and Max children of a gateway (see below).

The gateway logs in as itself. Children never get credentials of their own and never log in.

Topics and payloads

All gateway topics use QoS 1.

Topic (gateway to Hermetry)	Payload	Meaning
`v1/gw/connect`	`{"device": "Meter A", "type": "lorawan-meter"}`	The child is present. `type` is optional and chooses the child’s profile.
`v1/gw/disconnect`	`{"device": "Meter A"}`	The child is gone.
`v1/gw/telemetry`	See below	Readings of one or more children.
`v1/gw/attributes`	`{"Meter A": {"lora.rssi": -97}}`	Client attributes of one or more children.

Telemetry is an object keyed by child name. Each child holds one record or a list of records:

{
  "Meter A": [
    {"ts": 1759572000000, "values": {"kwh": 1203.4, "voltage": 229.8}},
    {"ts": 1759572060000, "values": {"kwh": 1203.6, "voltage": 230.1}}
  ],
  "Meter B": {"values": {"flow_m3h": 12.7}}
}

ts is the time in milliseconds when the value was obtained. Leave it out when the gateway’s clock is not set; Hermetry then uses the arrival time. See Timestamps, late and duplicate readings.
values follows the same key and value rules as any device’s telemetry. See Telemetry keys.
A record may carry an optional meta object with facts about the reading, for example "meta": {"lora": {"rssi": -97, "snr": 7.5}}. meta is at most 256 bytes. It is never stored as a reading. Only its lora and snmp members (each at most 8 plain values) are passed on to your flows as message metadata; everything else in it is ignored.
A record without values, or with a ts that is not a positive number, is skipped. The rest of the message is kept.

An optional client attribute time_quality on a child, {"source": true, "arrival": false, "synced": true}, says whether timestamps come from the child’s own clock, from the gateway’s arrival time, and whether the gateway’s clock was synchronised. It is informational.

How children are created

Hermetry creates a child the first time the gateway reports it, by connect, telemetry or attributes. A child seen in telemetry without a connect counts as connected.

The child belongs to the gateway’s organisation. It is never claimed separately.
Profile, in this order: a profile in your organisation named exactly like the type sent in connect; else the gateway profile’s Profile of new children; else the built-in Generic child profile, which Hermetry creates the first time it is needed. A child announced without type skips the first step.
Device name: the child’s wire name. If a device with that name already exists in your organisation, the name becomes <wire name> · <gateway name>, then that name with 2, 3 and so on.
Renaming the child in Hermetry does not change its wire name. The gateway keeps addressing it by the name it sent.
The first records of a brand new child can be dropped while it is being created. Hermetry asks for the child once and the next message finds it.

Child names

Rule	Value
Length	1 to 128 characters
Not allowed	Control characters, a leading or trailing space
Case	Case-sensitive: `abc` and `ABC` are two children of one gateway
Uniqueness	Per gateway

A name that breaks a rule is skipped and counted; the other children of the message are kept.

A device that connects directly wins. If the child name equals the serial number of a device in your organisation that has its own credentials (compared without regard to case), the child is refused (child_conflict_direct) and no child is created. This keeps a device that runs its own cloud session from appearing twice.

Limits

Limit	Value
Children per gateway	The profile’s Max children of a gateway (default 500), never above your plan’s value (500 when the plan names none) or the platform ceiling of 1,000
Device limit	Each child counts toward your plan’s device limit
One gateway message	At most 64 KiB, or the gateway profile’s Max message payload (bytes) if lower
Children in one message	500; more are skipped
Records per child in one message	1,000; more are skipped
`meta` per record	256 bytes

A child that would go over the child limit or the device limit is refused (child_limit or device_limit), and its records are dropped.

Rate limits apply twice. First the gateway’s own profile limits count the whole message, including every child’s data points. Then each child’s own profile limits apply to its part: a child over its limits loses only its own records (child_rate_limited). See Device profiles for the limit fields and Message quota and usage.

Connection state

connect and disconnect set the child’s connection state.
When the gateway goes offline, all its children go offline with it.
A disabled child is dropped within about a minute: its records are no longer accepted.

Commands to children

Sending commands and shared-attribute changes to a child through its gateway is in development. Do not build on it yet. See Commands to devices behind a gateway.

Troubleshooting

Symptom	Cause and fix
The gateway is disconnected after a few `v1/gw/*` messages	The device is not marked as a gateway. Three rejected topics in a minute close the session. Turn on This device is a gateway.
No child appears	The child name breaks a rule, the child or device limit is reached, or a direct device uses that serial. Check your device count under usage.
A child has the wrong profile	The `type` does not match a profile name exactly. Rename the profile or set Profile of new children on the gateway’s profile. Changing the profile of an existing child is done on the child’s device page.
A child shows two names	A device with the wire name already existed, so the child was named `<wire name> · <gateway name>`.