Sensor onboarding

Overview

A sensor whose model is not in the model list can still be added to Omaya. Device > New sensor types guides the onboarding, using the device's own live messages to work out what it reports.

The result is a decoder owned by the organisation: a short description of which bytes of the device's message mean what. The next unit of that model is recognised on sight, and its readings go to the same reports, rules and alerts as any sensor Omaya already supports.

Check the model list first: Devices and what they report. If the model is listed, selecting it when the device is registered is sufficient; onboarding is for models that are not listed. The list at the foot of step 4, Already in the platform library, shows decoders other organisations have shared, which Omaya already applies on sight.

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.

The page has four steps along the top: Find it, Listen, Understand and Confirm. Its tab strip has Learn a sensor (the onboarding itself) and, for roles that can manage general configuration, Custom types and Test decode.

Onboarding a new sensor

Applicable versions / plans

SPECIFICATION

• Menu: Device > New sensor types, permission manage-devices (Bulk Import Devices; Admin and Manager as shipped). If the item is missing from the menu, the role does not have it.
• Custom types tab: permission manage-config-general, which not every device manager has.
• Decode Assist (step 3) uses the AI model set on the AI card under System > Configuration. Without one, a decoder can still be written by hand on the Custom types tab.
• Bluetooth sensors heard by a gateway, and LoRaWAN devices whose messages a network server delivers.

Requirements

At Northwind Tower, Daniel Lim has a box of ten temperature-and-humidity sensors for the Server Room on Level 2, from a maker Omaya does not know, with the datasheet that came in the box. He onboards the first one and registers the other nine as ordinary sensors.

• A decoder named after the model, reused for every unit.
• The first sensor registered as Server Room temp 1, in the Server Room zone.
• Temperature and humidity in the Environment report.

Restrictions

• The sensor must be switched on near a gateway. Omaya learns only from messages it receives; a sensor still in its box in another building cannot be onboarded.
• Listening runs while the page is open, not in the background. Closing the tab stops it.
• The manual or datasheet, if available (a PDF, a link or the text), makes the difference between an answer and a guess. Vendors describe their message format far better than the bytes alone can reveal.
• A typed address must be a Bluetooth MAC address or, for LoRaWAN, the 16-character DevEUI.
• Decode Assist gives up after five minutes.

Configuration roadmap

(1) Find the sensor and select it.

(2) Capture its messages while making its readings change.

(3) Let Decode Assist propose the fields, and check the values against the room.

(4) Confirm what each field counts as, name the sensor and the decoder, and save.

Procedure

Step 1: Find it.

1. Switch the sensor on near a gateway.
2. Choose Device > New sensor types. Within a minute the sensor appears in the list, strongest signal first, so the one in hand is usually at the top. Each row shows the device's name or maker if it announces one, its MAC address, the gateway that hears it and when. LoRaWAN devices are marked LoRa.
3. Click Use this on its row. Alternatively, type the MAC address, or for LoRaWAN the 16-character DevEUI, from the label.

If the sensor does not appear, see Troubleshooting.

Step 2: Listen. Omaya collects the device's messages and shows, as they arrive: messages heard, Kinds of message, Values changing, the gateways it was Heard by and the Signal.

1. Make the readings change while Omaya listens: warm the sensor in the hand, press its button, walk past it, open the door, according to what it measures. This is how the measurement is distinguished from the rest of the message.
2. Wait until a few messages have arrived; more improve the result. Advanced: raw messages and frame anatomy shows the bytes themselves.
3. Click Next: understand it. Pick a different sensor goes back; Stop listening ends the capture.

Exercise the sensor fully

Many sensors interleave several kinds of message (one with the readings, one with the battery, one that only identifies the device), and some send a field only when something changes. A decoder built from thirty seconds of idle advertising decodes idle advertising and nothing else.

Step 3: Understand.

1. Under Manual or datasheet, click Attach for a file, Fetch for a link, or Use pasted text. Anything you know about it takes a note, such as the model number or the sensor's purpose.
2. Click Ask Decode Assist. Decode Assist reads the captured messages, and the manual if there is one, and proposes what each part of the message means. It can take a minute or two; the page says so while it works. It returns:
   • its guess at the make and model, with a Confidence;
   • a table of readings: each field, the value it decoded while listening, and what it Counts as, each marked checks out against every message, partly checks out, does not match the messages or not usable;
   • Not worked out: parts of the message it could not explain;
   • Why it thinks so: its reasoning, in words.
3. Check the values against the room (see the caution below).
4. If the values are correct, click Looks right — continue. If not, click Ask again, with a note about what was wrong.

Decode Assist proposes the middle column for you, and step 3 is where you check it: a reading of 2250 °C would mean the × 0.01 is missing, and 22.50 °C in a warm office is believable. Only a field with a Counts as choice reaches a report; anything left as extra detail is kept but nothing reads it.

Check the values against the room

This check decides whether the decoder is right. A temperature of 3 °C in an office is a scaling error, not a cold office. The battery should be plausible for a newly unpacked device. Pressing the button, warming the sensor or walking in front of it should move the reading as expected. A decoder with three correct fields is worth more than one with six of which two are wrong, because nothing downstream can tell which is which.

Skip — just register it goes to step 4 with no decoder, to register the device as it is; a decoder can be added later on the Custom types tab of Device > New sensor types.

Step 4: Confirm. What it reports lists each field with what was Seen and what it Counts as.

1. Check the Counts as choice for each field (see the table below).

2. Set the fields as follows.

   Configuration Item	Value	Note
   Sensor name	Server Room temp 1	The name people use for the sensor.
   Where is it?	Server Room	A zone, or Same place as the gateway that hears it.
   Decoder name	Acme TH-20	Reused for other sensors of the same kind. Required.

3. Click Save decoder & register sensor.

Only a field with a Counts as choice reaches a report; a field left as extra detail is stored but nothing reads it. The choices are the standard reading names, and each decides where the reading lands:

Counts as	Where it is shown
Temperature, humidity, noise, light, pressure, CO₂	The Environment report, and rules on that reading
Battery	The Battery report
People count, occupied	Occupancy for the room the sensor is in
Distance	The Distance report
Button press	The Trigger Event report, and rules on presses
Energy (kWh, W, V, A)	The Energy app

The full list with units is under Standard reading names.

Advanced: decoder spec

Advanced: decoder spec shows the field-by-field specification and the Match prefix (hex): the opening bytes that distinguish this model's messages from every other device's. Re-check against the messages tests an edit before saving. Most onboardings do not need it.

Verification

• The page shows Done. <sensor name> is registered and its readings will show in reports within the hour. From then on it is an ordinary sensor.
• If Decoder name is empty, the page shows Give the decoder a name — it will be reused for other sensors of the same kind.
• The next day, check the readings in the Environment report and on the device's own page. A decoder that looked right for five minutes can still be wrong about a field that changes slowly, a counter that wraps, or a byte that means something different when a flag is set.

After onboarding

Registering further units

Register the second unit normally on Device > Sensor; no onboarding is needed. A Bluetooth sensor is recognised by its match prefix, so Decoder can stay on Automatic (match by advertisement). A LoRaWAN device finds its decoder only if it is selected in Decoder. Bulk Import, on the Device > Sensor page, registers the rest of the box.

Editing a decoder

The Custom types tab of Device > New sensor types lists every decoder the organisation has, with its match prefix and spec, and a What each field counts as selector per field. A decoder can also be written there from scratch, from a datasheet, without capturing anything.

Sharing a decoder

After saving, Share this decoder with the platform sends the decoder for review (also on the Custom types tab, as Share with platform). The row then shows its status: proposed, published, rejected or retired. Once the Omaya operator publishes it, every organisation's sensors of that kind decode with no setup; this is how the supported list grows.

When onboarding does not apply

• A LoRaWAN device whose messages nothing delivers. Omaya decodes LoRaWAN payloads, but a network server has to deliver them first; see Milesight LoRaWAN gateways. Once the traffic arrives, onboarding works the same way, and step 2 also shows what the network server's own codec made of each message.
• A message encrypted with a key that is not available. No amount of listening recovers it. Obtain the key from the vendor.
• A device Omaya already supports. Check the model list first. Selecting the right model takes one choice; onboarding takes considerably longer.
• A measurement not on the Counts as list, such as motion, vibration or a radar track. The reading can be stored, but no report reads it until the platform supports that kind of measurement. Save the fields that fit, and report what is missing to the Omaya operator.

Troubleshooting

Symptom	Cause	Action
The sensor does not appear in step 1	It is not transmitting: some devices ship in a sleep or shipping mode.	Wake it with a magnet, a button press or by pulling the battery tab.
The sensor does not appear in step 1	It is out of range.	Bring it within a few metres of a gateway.
The sensor does not appear in step 1	The gateway is offline.	Check Device > Gateway.
The sensor does not appear in step 1	It is a LoRaWAN device and nothing delivers its messages yet.	See When onboarding does not apply.
Enter a BLE MAC like C3:00:00:19:1F:09 or a LoRaWAN DevEUI (16 hex characters).	What was typed is neither.	Copy it from the label, with or without the colons.
No captured frames yet — listen first.	Decode Assist was asked before any messages arrived.	Return to step 2 and wait for messages heard to increase.
No text could be read from that PDF (a scanned image?). Try a text export or paste the payload section as a .txt.	The manual is an image of text.	Paste the section that describes the message format, or attach a text version.
Decode Assist did not answer within five minutes. Try again.	No answer from the AI provider.	Click Ask again. If it keeps failing, check the AI card under System > Configuration, or write the decoder by hand on the Custom types tab.
No AI provider is configured for this organisation (System → Configuration → A.I Model). or This month's shared AI allowance is used up.	Decode Assist has no model to ask.	An administrator selects a provider (or adds the organisation's own key) on the AI card under System > Configuration; the shared allowance resets at the start of the month. Meanwhile, write the decoder by hand on the Custom types tab.
The AI provider is rate-limiting right now — try again in a minute.	The provider is busy.	Wait a minute and click Ask again.
Give the decoder a name — it will be reused for other sensors of the same kind.	Decoder name is empty.	Fill in Decoder name in step 4.
The values were right yesterday and wrong today	The message probably has more than one layout, and today's readings came from one the decoder never saw.	Onboard again with the device exercised fully, or edit the spec on the Custom types tab.