Wialon Retranslator: Protocols and Configuration

Retranslation is Wialon forwarding device messages to another server over a protocol that server already speaks. It is the only push path out of the platform, and it is the right answer more often than integrators expect, because pulling the same data through the Remote API costs a session, a share of the message quota and a polling loop that has to be maintained forever. This page covers what a retranslator is as an object, the nine protocols and the configuration each one takes, and how retranslation compares to an API pull once both are in production.

Treat configuration, membership and run state as three separate things

A retranslator is an item in Wialon, alongside units, users, resources and routes. It is created with core/create_retranslator, then configured, then given units, then started. The retranslator chapter lists the commands available against it: add and remove units, start and stop, status of history retranslation, and update configuration.

That separation matters operationally more than it looks on paper, because the three states fail independently and none of them reports the others. A retranslator can be correctly configured, hold exactly the right units, and be stopped — and from the receiving end that is indistinguishable from one that was never set up at all. When a stream goes quiet, check run state before checking configuration, because it is both the more common cause and the faster one to verify.

Send only the config parameters your protocol accepts

Configuration goes through one command carrying a protocol name and a set of connection parameters:

svc=retranslator/update_config&params={
  "itemId":<long>,
  "config":{
    "protocol":<text>,
    "server":<text>,
    "port":<ushort>,
    "v6type":<text>,
    "auth":<text>,
    "attach_sensors":<bool>,
    "ssl":<text>,
    "login":<text>,
    "password":<text>,
    "notauth":<int>
  }
}

The configuration reference states that the set of parameters in the config object depends on the protocol type, and the per-parameter notes make the dependencies explicit rather than leaving them to be discovered:

Sending a parameter that a protocol does not use is the first thing to check when a configuration is rejected. So is assuming that transport security is available across the board: ssl is documented for NIS, and there is no general secure-connection switch that applies to the other eight.

Decide attach_sensors deliberately rather than by default

The attach_sensors flag looks like a formatting preference and is an architectural choice. For the two Wialon protocols it controls whether calculated sensor values travel with the message or only the raw parameters underneath them, and the two options put the fuel mathematics in different places.

Forwarding calculated values means the receiving system inherits Wialon’s sensor configuration: its calibration tables, its validation rules, its interpretation of what a given voltage means in litres. That is convenient, and it means the receiver’s numbers agree with the platform’s numbers by construction — until someone edits a calibration table on the Wialon side, at which point the receiver’s historical series silently changes meaning partway through with nothing recording that it happened. Forwarding raw parameters puts the interpretation in your hands and requires reimplementing all of it, after which the two systems will disagree the first time either implementation drifts.

When the destination is a warehouse you own, taking both is usually the right answer rather than choosing. Raw parameters become the source of truth that can be reprocessed when a formula changes, calculated values become a running check against your own implementation, and divergence between the two is the earliest available signal that a sensor was reconfigured on the platform without anyone telling the data team.

Run retranslation and API pull together, and plan for duplicates

Retranslation and the Remote API are not alternatives so much as two halves of a working integration, and the trade between them is straightforward once stated.

Retranslation pushes, which means no session to keep alive, no polling loop, no session identifier to refresh, and nothing consumed from the message quotas that bound the Remote API. The fifteen-million-messages-per-two-minutes ceiling and the three-heavy-requests-per-session limit apply to what you pull, not to what Wialon sends you, so for continuous ingestion this is the cheaper path by a wide margin and the one that scales without new engineering.

The Remote API pulls, and pulling is the only thing that can look backwards. Retranslation delivers what arrives from the moment it is running; anything historical still comes through messages/load_interval, which is why status of history retranslation exists as a separate command and why a real integration ends up running both — retranslation for the live stream, API pull for backfill and for healing whatever the live stream missed.

Build the dedup key before the second path exists

Running both paths has one consequence that has to be designed for at the start rather than discovered in production. Two routes carrying the same messages makes duplicates certain rather than possible: a restarted retranslator resends, a replayed history window overlaps, and a backfill run to close a gap will always cover more than the gap. They will also arrive out of order relative to each other, because the live stream is roughly real time while a backfill delivers a week of history in minutes.

Deduplicate on a composite key rather than trusting arrival order or a sequence number, and make the loader idempotent before either path reaches production. Retrofitting idempotency onto a warehouse that already contains duplicates is a materially harder problem than building it in, because the cleanup has to distinguish a genuine repeated reading from an artefact of the ingestion, and by then nobody remembers which run produced what.

Stand one up before the retention window closes

Retranslation does not remove the platform’s retention boundary, and that is the argument for setting one up earlier than a project appears to need it. Wialon Hosting keeps unit history for 400 days by default and removes older messages from the database automatically, so once a retranslated copy exists it is the only place that data continues to live past the window.

The asymmetry is what makes this urgent rather than merely sensible. Configuring a retranslator later is easy and costs an afternoon; recovering the months that expired while nobody had one is impossible at any price. Every month of delay is a month that will simply be absent when someone eventually asks for a two-year comparison, and the request always arrives after the data would have been needed rather than before.

The forum recorded how most people met this protocol: “Python server for Wialon Retranslator v1.0” drew 32,113 views across 33 replies, one of the most sustained developer discussions on the board and good evidence that nearly everyone using it was writing their own receiver. The board is offline, every URL now redirects to the help.wialon.com root, and captured pages survive for roughly 61% of threads in the Wayback Machine.

• Check run state before configuration when a stream goes quiet — stopped and misconfigured look identical downstream.
• Decide attach_sensors deliberately, and prefer taking raw parameters alongside calculated values.
• Build the dedup key before the second ingestion path exists, not after.