TagoIO User Guide

01Overview

TagoIO is a cloud IoT platform. This app makes your Atrium gateway report into it. You supply two TagoIO credentials once, pick which of the gateway’s sensors should report, and from then on the gateway creates the TagoIO devices, keeps their names and tags in step with Atrium, and pushes every reading as it arrives.

The gateway acts as a multiplexer. It holds a single set of TagoIO credentials and reports on behalf of every sensor you enable, so you do not create or manage TagoIO devices by hand and there is no per-sensor credential to distribute.

02Requirements

TagoIO needs a gateway new enough to host apps that subscribe to sensor traffic and configure sensors, plus a TagoIO account you can generate two credentials in.

03Installing

TagoIO installs from the Atrium App Center like any other app.

1. 1
   Open the Apps tab

   In Atrium, click Apps in the top navigation, then Browse App Center.
2. 2
   Find TagoIO

   It is listed with the subtitle TagoIO and the badge TI. There is no PAID badge, so no license step.
3. 3
   Install it

   Both platform services restart, so the gateway API is briefly unavailable. The card then reads INSTALLED.
4. 4
   Click Open on the TagoIO card

   The app opens on its Connection screen. Alongside Open the card also carries Update and Uninstall.

What installing changes

• The app derives a gateway prefix for TagoIO serials from the gateway’s name — “Gateway B00E” becomes b00e. See Serial namespace.
• No outbound request is made and nothing is created in TagoIO. Until you connect an account, the app is inert.

04First-Time Setup

Four steps take you from a freshly installed app to sensors reporting into TagoIO with a dashboard that can change their settings. Everything else in this guide is detail on these four screens.

2. Connect the gateway

1. 1
   Open the Connection screen

   It is the app’s first screen. The panel reads Not connected and the form below is headed Connect to TagoIO.
2. 2
   Choose your Region

   us-e1 or eu-w1, matching the region your TagoIO account lives in. This decides which TagoIO hosts the gateway talks to.
3. 3
   Paste the Profile token and Authorization

   Both fields are masked. Connect stays disabled until both contain something.
4. 4
   Click Connect

   The button reads Verifying… while the gateway checks the token against TagoIO. On success the message Connected to TagoIO. appears, the chip turns Connected, and the panel fills in your account and profile name.

3. Choose which sensors report

Nothing reports until you say so. Open Devices and use the Report switch on each sensor you want in TagoIO.

Turning a switch on assigns that sensor a permanent TagoIO serial and creates its TagoIO device immediately, so the State column normally moves to On TagoIO within a second or two. If TagoIO is unreachable the sensor sits at Pending and a background worker keeps retrying, so you can enable sensors before the link is healthy.

4. Build the TagoIO dashboard

This step is only needed if you want to change sensor settings from TagoIO. If you only want readings flowing in, you are already done after step 3.

Open Configuration and click Set up in TagoIO. The gateway creates four things in your TagoIO account and reports each one’s state. Once all four read Ready, Open dashboard takes you to it.

05Connection

The Connection screen is where the gateway’s link to TagoIO is established and checked. It refreshes itself every 5 seconds, which the panel states as Polls every 5s.

Verify, test, disconnect

Three buttons appear once credentials are stored. None of them writes data to TagoIO.

Verify now

Re-checks the stored profile token against the TagoIO REST API and refreshes the account and profile names. On success it reports Credentials verified. This is the check to run when device creation is failing.

Test telemetry endpoint

Checks the other half — the Authorization hash used for telemetry, which Verify now does not cover. It pushes to a randomly named serial that cannot exist. TagoIO resolves the profile before it looks up the serial, so a device_not_found answer proves the hash is valid, while invalid_token proves it is not. No data is written either way, and no real device is touched.

Success reads Authorization hash accepted by the TagoTiP endpoint. Failure reads The TagoTiP endpoint rejected this authorization hash.

Disconnect

Deletes the stored credentials from the gateway. Reporting stops immediately. Your TagoIO devices and their data are left exactly as they are, and so are the gateway’s device mappings, so reconnecting the same profile resumes where it left off.

06Devices

Devices is where you decide which sensors reach TagoIO, and where you check that they are getting there. The heading counts the sensors Atrium has set up, for example 3 whitelisted sensor(s); the count on the sidebar item is how many are enabled for TagoIO.

Removing a device

Remove is the only way to free a serial, which matters if a sensor was mapped by mistake. Because serials are permanent on TagoIO, this is a real deletion, so it is confirmed inline: the row’s buttons become Delete on TagoIO and Cancel.

If TagoIO refuses the delete, the app offers a second path rather than leaving you stuck: a panel explains that TagoIO would not delete the device and offers Forget the mapping, which frees the serial locally and leaves the TagoIO device, if any, alone. Use it when you already deleted the device in the TagoIO dashboard yourself.

07Configuration

Configuration is the gateway’s side of two-way sensor settings. As the page itself says: settings changes made in TagoIO land here first, the gateway validates every value against the sensor’s own options before it touches the radio, then waits for the sensor’s next check-in — so a change is normally pending for one report interval.

This is the screen to open when someone says “I changed the interval in TagoIO and nothing happened”. Sync now in the header runs a pull, acknowledge and publish pass immediately instead of waiting for the next minute, and reports what it did.

Per-sensor cards

Each mapped sensor gets a card headed with its name, then its serial, sensor type and firmware version.

The schema chip

Chip	Meaning
Schema published	The gateway knows this sensor type’s settings and TagoIO has the current list.
Schema pending	The gateway knows the settings but TagoIO does not have the current list yet.
No schema	The gateway has not read this sensor type’s options yet, so it will not forward changes at all — it refuses to send values it cannot validate. This resolves on its own once the ingestion daemon has seen the sensor.

The timing line

Five values, and they mean genuinely different things:

Value	Meaning
sensor seen	When the sensor last checked in over the radio. A change cannot be delivered until this happens again.
polled	When the gateway last checked TagoIO for requested changes for this sensor.
rev	The revision counter the gateway has processed. It moves when someone applies a change in TagoIO.
reported	When the sensor last told the gateway what its settings actually are.
sent to TagoIO / not sent to TagoIO yet / nothing to send yet	Whether TagoIO holds that reported set. This is deliberately separate from reported, because a sensor reporting successfully while TagoIO never receives the values looks identical otherwise — and is exactly the case where a widget shows a form with no current values.

Reported settings

Show reported settings (n) expands the sensor’s current configuration as the sensor itself reports it. This is ground truth from the hardware, not what was requested.

08Settings

Four panels, each with its own Save button. Saving one panel does not affect the others.

Serial namespace

Every TagoIO serial is <prefix>-<address>, where the address is the last four bytes of the sensor’s radio address. The prefix keeps several gateways from colliding inside one TagoIO profile.

Field	Detail
Gateway prefix	Derived at install from the last word of the gateway’s name — “Gateway B00E” becomes b00e. Editable only while nothing is mapped. The value is lower-cased, characters outside a-z 0-9 _ – become a hyphen, and leading and trailing hyphens are dropped.
Resulting serial	A live preview built from a real sensor on this gateway, so you can see the effect before saving.

Telemetry

Setting	Default	Effect
Send battery and signal strength	On	Adds battery_percent and rssi to every push. Makes sensor health visible in TagoIO at the cost of two extra data records per reading. Turn it off to reduce TagoIO consumption.
Replay readings missed while TagoIO was unreachable	On	Readings are sent with their original timestamps, so a gap fills in at the right place in the history rather than arriving as “now”.
Maximum replay window (hours)	24	How far back a gap may be filled, from 1 to 168 hours. Anything older is skipped, so a gateway offline for a week does not flood TagoIO when it returns. Disabled while replay is off.

Sensor configuration

Accept settings changes from TagoIO (default on) lets a TagoIO dashboard change sensor settings such as the report interval. The gateway validates every value against the sensor’s own options before it reaches the radio, and publishes each sensor’s available settings so the dashboard can build its form.

Clear it to make the integration strictly one-way — readings out, nothing in. Set up in TagoIO is refused while it is off.

TagoTiP integration

Collapsed by default behind a Show button, because these are fixed TagoIO platform ids for TagoTiP over HTTP. As the panel warns: change them only if TagoIO asks you to — a wrong value makes every device creation fail.

Field	Detail
Network id	The TagoIO network id for TagoTiP over HTTP.
Connector id	The matching connector id.
Device type	mutable (default), immutable or hybrid. Only affects devices created from now on. immutable also needs chunk settings on TagoIO, so mutable is the safe default.

09Diagnostics

Diagnostics shows exactly what the gateway sent to TagoIO, straight from the ingestion daemon. Use it to confirm whether a variable is being published before hunting for it in a TagoIO dashboard.

Live push status

Recent pushes

The last 25 pushes, newest first. Each entry shows the outcome chip (Sent, or the failure code), the serial, the time, and how many values the push carried. Beneath that is the actual TagoTiP payload, with each variable name and value shown as its own pill so you can pick a name out of the frame.

Two lists follow each payload, and the difference between them is the point:

• Frame fields — the metadata the sensor’s frame carried, such as battery, RSSI and counter. Sensors disagree about which of these they send.
• Decoded values — the measurements the sensor’s decoder produced.

If a variable you expect is missing from a TagoIO dashboard, check here first. A name absent from both lists was never sent by the sensor, which is a sensor or decoder question rather than a TagoIO one.

With nothing to show, the panel reads No frames pushed yet. Enable a sensor on the Devices page and wait for its next report.

10Changing Settings from TagoIO

This section is the TagoIO side of the integration — the dashboard the gateway built for you in step 4 of First-Time Setup, and what your team does with it.

Open it from Configuration → Open dashboard, or find the dashboard named NCD Sensor Configuration in your TagoIO account.

The widget

The dashboard carries one custom widget. When more than one sensor is bound to it, the widget’s title is replaced by a sensor picker, so one widget serves the whole fleet rather than needing one per sensor.

Under the picker is a line reading the sensor’s type, firmware version and last check-in time. That header stays pinned while the settings list scrolls, so you always know which sensor you are editing.

Below it is a form built from that sensor’s own settings list — which is why the gateway publishes the schema, and why a new firmware’s settings appear without anyone updating a dashboard. Each row carries up to five things:

Applying a change

1. 1
   Pick the sensor

   Use the picker at the top of the widget. Options are listed alphabetically.
2. 2
   Edit the settings you want to change

   A count of unsaved edits appears next to the button that acts on them.
3. 3
   Click Apply changes

   The button sits at the bottom of the widget and stays reachable however long the settings list is. It reads Sending… while it works. A Discard button appears next to it only once you have unsaved edits, and abandons them.
4. 4
   Wait for the sensor’s next check-in

   The widget shows the change as pending until the sensor confirms it, typically one report interval.

Messages the widget shows

11What the Gateway Publishes

What arrives in TagoIO, and what it is called. This is the section to read before building a dashboard or an Access Management rule.

Device identity

Telemetry variables

Each sensor frame becomes one TagoTiP group. Decoded values keep the names Atrium normalizes them to, so live and replayed values land on the same TagoIO variable. Numeric strings are converted to numbers so TagoIO can chart them; booleans stay booleans.

Alongside the decoded values, whichever of these the frame carried is sent:

Sensors disagree about which frame fields they report, so whichever are present are sent rather than a fixed set being assumed. If a decoder already reports a value itself, that wins over the frame-level copy, so nothing is published twice.

Device tags

The app maintains ten tags, against a TagoIO limit of 30 per device — leaving room for your own. Tag values are always strings, and an empty value is omitted rather than sent blank.

Battery, RSSI, last-seen and status are deliberately not tagged. They change constantly, and keeping them accurate would mean an API write per reading; they are published as variables instead.

Device tokens

Each device the app creates carries two tokens. TagoIO’s own Default token holds the device’s serial number, and the app adds one named atrium-app, which is what it uses to write data. Leave both in place — deleting atrium-app stops that device receiving its configuration records until the gateway mints a replacement.

Configuration variables

These exist only when sensor configuration is enabled, and are what a widget binds to.

12Atrium Integration

What the app reads from the gateway, what it writes, and how it relates to the rest of Atrium.

What it reads

• Gateway configuration — model, name and modem MAC, used for the serial prefix and the gateway tags.
• Sensors and their metadata — the sensors Atrium has set up, with their names, locations, assets, firmware, last-seen and battery, for display and for the TagoIO tags.
• Readings — only when replaying a gap, and always narrowed to one sensor, one metric and a bounded time range.
• Sensor frames as they arrive — the live push path.
• Sensor settings options — each sensor type’s settable settings, used both to publish the schema and to validate an incoming value.

What it writes

• Nothing in Atrium’s own data. The app writes only its own database, and requests sensor settings changes through the platform’s device twin — the same mechanism Atrium’s own screens use.
• Credentials are encrypted at rest by the platform’s secret store. They are never returned by the app’s API and never written to logs; only a four-character tail of the profile token is ever displayed.

Where changes come from

Atrium keeps a Desired and a Reported set of settings per sensor and pushes the difference when the sensor checks in. TagoIO edits Desired and displays Reported; it never talks to a sensor directly. That means a settings change made in Atrium and one made in TagoIO go through the same path, and the Configuration screen will pick up a change made outside this app.

13Troubleshooting

Symptoms in the order you are likely to meet them. In general: the Connection screen tells you whether credentials work, the Devices screen whether TagoIO devices exist, and Diagnostics whether readings are actually leaving the gateway.

Connecting

Devices

Telemetry

Sensor configuration

14Reference

Endpoints the gateway contacts

Regions are us-e1 and eu-w1. All traffic is outbound HTTPS; nothing needs to reach the gateway from the internet.

Timing and limits

How a settings change travels

TagoIO widget  ->  Trigger  ->  Validator  ->  device parameters (pending)
                                                       |
                                    gateway notices the revision move
                                                       v
                              gateway validates against the sensor's options
                                                       |
                                                       v
                                        radio  ->  sensor applies it
                                                       |
                                       sensor reports what it applied
                                                       v
                                    acknowledged back to TagoIO (pending clears)

Two properties of that path are worth remembering. The gateway validates every value against the sensor’s own options before anything reaches the radio, independently of TagoIO having validated it. And a change is acknowledged only once the sensor confirms it, which is why a dashboard’s pending state is meaningful rather than cosmetic.

What the app stores on the gateway

Everything the app keeps is bounded by the number of sensors on the gateway, so there is no retention policy to manage and no growth to watch.

• No telemetry is ever copied. Only a cursor per device — the newest reading confirmed delivered. That is what makes replay work without a retry queue: a failed push simply leaves the cursor behind.
• The TagoIO link: region, both credentials encrypted at rest, the derived authorization hash, and the account and profile the token belongs to.
• One row per enabled sensor: its serial, sync state, TagoIO ids, retry and push bookkeeping.
• One settings schema per sensor type and firmware, rather than per sensor, so a fleet of identical sensors stores one copy.
• Requested settings, and the last settings each sensor reported.

Artifacts created in your TagoIO account

All four are tagged atrium_managed=1. The content hash in the widget path means an upgraded widget arrives at a new address, so nobody is left looking at a cached copy of the old one.