Teaching Omaya a sensor it has never seen

You bought a sensor that is not in the model list. That is not a dead end: Device → Sensor Onboarding walks you through it, using the device's own live packets to work out what it is saying.

The result is a decoder your organisation owns. The next unit of that model is recognised on sight.

Before you start

Three things, and the third one is the one people skip:

1. The sensor, powered on, within range of one of your gateways. Not the one still in the box in the other building.
2. Which gateway it is near. You will pick it, and it decides whose packets get collected.
3. The manual or datasheet, if you have one. It makes the difference between a good answer and a guess. Vendors describe their own payload far better than any amount of staring at bytes can reconstruct.

Keep the page open

Packet collection runs in your browser session, not in the background. Close the tab and it stops. Onboarding one sensor is a few minutes of attention, not something to start and walk away from.

Step 3 is the one that decides whether the decoder is right, and it is the one people skim. A temperature reading of 3 °C in a warm office is a scaling error, not a cold office — and three fields that are correct beat six where two are fiction, because nothing downstream can tell which is which.

Step 1 — which sensor

Switch the sensor on near the gateway you chose. Within a minute it appears in the list, strongest signal first, so the one in your hand is usually at the top.

If it does not appear, it is nearly always one of three things: it is not transmitting (some devices ship in a shipping mode and need a magnet or a button press), it is out of range of that gateway, or the gateway itself is offline — check Device → Gateway before suspecting anything cleverer.

You can also type the MAC address or DevEUI straight in, off the label.

Step 2 — collect some messages

Omaya listens and collects frames. Give it long enough to see the device's whole repertoire rather than one frame repeated.

That phrase matters. Many sensors interleave several different message types — one with the readings, one with the battery, one that is just an identity beacon — and some only send certain fields when something changes. If the device has a button, press it. If it reports on movement, move it. A decoder built from thirty seconds of idle advertising will decode idle advertising and nothing else.

Step 3 — what does it measure

Attach the manual first if you have one. Then Decode Assist reads the collected messages and proposes what each part of the payload means: which bytes are the temperature, where the battery is, what scaling turns the raw integer into a real value.

You get back a list of readings with the values it believes it is seeing right now. Check them against reality — this is the step that decides whether the decoder is right:

• Does the temperature match the room? A sensor reading 3 °C in an office is a scaling error, not a cold office.
• Does the battery look plausible for a device you just unboxed?
• Press the button, walk in front of it, breathe on it — does the reading move the way it should?

If a field is wrong, correct it or drop it. A decoder with three fields that are right is worth more than one with six where two are fiction, because nothing downstream can tell which is which.

Use the standard names

Each reading gets a name, and using the standard ones is what makes the value land in the right report with the right unit. temperature reaches the Environment report; my_temp_field is stored and ignored. The list of standard reading names.

Step 4 — confirm and save

Give the device a name and a place, and save. From that moment it is an ordinary sensor: its readings go to the reports, and rules and alerts can act on them like any other.

The decoder is saved too, under Device → Custom Decoders, where you can review or hand-edit the field-by-field specification later. If you have a datasheet and would rather not sniff packets at all, that page also takes a decoder written from scratch.

Afterwards

Add the second unit normally. Register it on the Device page and pick the model you just created. No onboarding needed — that was the point.

Check the readings the next day. A decoder that looked right for five minutes can still be wrong about a field that only changes slowly, a counter that wraps, or a byte that means something different when a flag is set. The Environment report and the device's own page are where that shows up.

Tell us about it. A decoder that works is worth having in the shared device library so every other organisation gets it too — that is how the supported model list grows.

When onboarding is the wrong tool

The device is on LoRaWAN and you have no network server. Omaya decodes LoRaWAN payloads, but something has to deliver them. Get the traffic arriving first; then the decoding is the same job.

The payload is encrypted with a key you do not have. No amount of listening recovers it. Get the key from the vendor.

It is a device Omaya already supports. Check the model list before you start. Picking the right model is a dropdown; onboarding is an afternoon.