Data transfer translators

A data transfer translator moves data from the device it runs on to another device in Yggio. The value is written onto the target through additionalDeviceUpdates rather than stored locally, so one device's reading can appear on another.

The device must have write access to the target. Addressing is by identifier: secret, imei, devEui, tag or serialNumber, chosen with targetIdentifierField and given in targetIdentifierValue.

Why forward data at all

Two quite different problems, both solved by moving data sideways.

Building a device that does not exist. Some calculations need inputs from several sensors at once. A building's energy efficiency needs energy from a meter, indoor temperature averaged across rooms, and an outdoor temperature from somewhere else entirely. No single device reports all of that. Forwarding collects the values onto one shared node, and the analytics or calculation translator then runs there, on a device assembled from an entire installation rather than from one sensor.

Separating connectivity from content. Whoever runs the network needs to see that a device is online and delivering. That is not the same as being allowed to read what it sent. If the payload is medical data, the operations team must not see it. forward-encoded-data splits the two: the raw frame arrives on a node the operator can monitor, is handed to the end user's own node to be decoded there, and is then removed from the source, where it cannot be recreated.

The translators

Translator	What it moves	Notes
forward-value	One canonical field, named in forwardField	Every catalogue field is declared in this translator's spec, so any canonical field name is accepted. Defaults to temperature
forward-values	Several fields at once, listed in forwardFields	Comma-separated, and each item may be source:target to rename on arrival, for example temperature,relativeHumidity:rh. Values land inside a single measurements object, which is what lets non-canonical and device-specific names through
forward-encoded-data	The raw, undecoded frame	Runs as the main translator on the source node, not chained: it does not decode, it forwards the payload and clears it. The device's real decoder lives on the receiving node

forward-value and forward-values are chained, running on top of the device's own translator and reading fields it has already decoded.

Grouping forwarded values

When several devices forward onto one shared node, the receiver needs to tell them apart. forward-values can nest a batch under a key:

• groupName puts the values under measurements[groupName], a fixed label you choose.
• groupBySourceName uses the sending device's own name instead, so a translator on the receiver can recognise which node sent what and handle each accordingly. It overrides groupName.

Sender and receiver share this shape as a contract, so decide it once and keep both ends in step.

Parameters

Parameter	Purpose
targetIdentifierField	Which identifier addresses the target: secret, imei, devEui, tag or serialNumber. Default secret
targetIdentifierValue	The target device's identifier. Required, and there is nowhere to send data without it
forwardField	forward-value only. The canonical field to forward. Default temperature
forwardFields	forward-values only. Comma-separated list, each entry source or source:target. Translator parameters do not yet support arrays, which is why it is a list in a string
groupName, groupBySourceName	forward-values only. Nest the batch under a fixed key, or under the sending device's name

All three set errorMessage when the target is not configured or there is nothing to forward.

Chaining

Forwarding is normally the last step on the sending device and the first input to a chain on the receiving one:

Sensors → forward-values → shared node → analytics-building-energy-efficiency → set-alarm-custom

The sensors contribute their readings, the shared node computes the figure that no single device could, and the alarm at the end reports on it like any other field.

For the full A–Z index of every translator, see the translators overview.