Gateway overview¶

For people who put the WLPC gateway software into a gateway: manufacturers who build their own image. Customers who only use the console can skip this section.

Supported architecture: currently armv7 only.

One program on the gateway talks to the platform: the Bootstrap-Agent. It proves the gateway's identity with the TPM, fetches the configuration your template describes, stores it, and hands it to your own software over a local socket. It does not start or stop your software, does not switch LEDs and does not delete data. That stays with your image.

Two ways to install¶

Install manually: for a single gateway, such as an integrator's test unit or a gateway already in the field. Every step runs on the gateway, with commands, no installer.
Install with Yocto and RAUC: for manufacturers who build gateways in series. The agent goes into your image and is updated with it. This is the recommended way for series.

Choose your path¶

You want to	Read	Notes
Build the agent into a Yocto image and update it with RAUC	Install with Yocto and RAUC	Signed release archive, pinned in a recipe, no installer, no root.
Install, update or remove the agent on a single gateway, without building an image	Install manually	Commands on the gateway; the archive is checked there before it runs.
Check that a download is genuine	Check the signature	Do this before you pin a version.
Tell the platform where the gateway connects to	Set the target on the device	Pallax workspace and gateway type belong to the device, not to the template.
Start your software when the configuration is there, and confirm the target	Start your software and confirm	A `.path` unit and one marker file.
Read the configuration from your own software	Local API reference	One Unix socket, no network port.
See every local call with a real answer	Local API examples	`curl` over the socket, values replaced.
Remove the agent from a lab gateway, or install it again	Uninstall	What stays in the TPM and in `/etc/iot-config`.
Find out why a gateway does not come up	Troubleshooting	`NO_CONFIG`, `TEMPLATE_INVALID`, TPM slots and the rest.

What runs, and as whom¶

The agent is one service, bootstrap-agent.service. It runs all the time and reacts to events. It is the only unit.

One process, one unit. The unit is Type=simple with Restart=on-failure and RestartSec=5s. The agent never calls systemctl and starts no other process.
Event driven. One loop waits for the local socket, for the check-in time (kept inside the agent) and for the confirmation marker (see Start your software and confirm). Measured on the lab device (conditions under Size): in 419 of 434 windows of 10 seconds the agent made no context switch at all; the other 15 windows are the 15 check-ins.
No privileges. The service runs as the user bootstrap-agent (created by the recipe), with the group tss, no capabilities and no new privileges. The only device it may open is the TPM resource manager /dev/tpmrm0. Measured on the lab device: all five capability sets 0, NoNewPrivs 1, user ID 988, one process with two threads.
Writes only two places: the state directory /etc/iot-config and /run/bootstrap-agent. It does not write LED or other system state.

Size on a gateway¶

Two different numbers, which are easy to mix up: what the agent occupies on the disk, and what it uses in RAM while it runs. Plan your image with both.

RAM while running. One run of 72 minutes on a lab device (armv7, one core, real TPM, read-only root file system), with an unsigned lab build of the agent, not a release build. The agent made 15 check-ins during the run. Memory was sampled 10 times a second.

Value	Measured	Meaning
PSS (shared memory counted proportionally)	3.6 to 4.84 MB, median 4.83 MB, highest 4.84 MB	Of this about 1.9 MB is the agent's own memory and about 2.9 MB are pages of the program and its libraries.
RSS (all pages the process touches)	7.29 to 7.32 MB	Counts the shared library pages in full.
Own memory growth	See Known gaps and limits	Measured in a longer run with a signed build. Known, not fixed.
CPU time	3.5 s in 72 minutes

The PSS varies because other processes on the device share the library pages; the highest value is the one that holds when no other process maps them. 95 % of the samples lie between 4.13 and 4.84 MB. This is a single run on one device: use it to size your RAM budget, not as a guarantee.

Disk. The program is 144,900 bytes (armv7, stripped, release flavour, built on Debian bookworm). It is linked dynamically, so your image must provide the libraries listed in Install with Yocto and RAUC.

Known gaps and limits¶

What the agent does not do, or what was not tested. Each item is a fact about this release line, not a promise.

Gap or limit	What it means for you
The agent never sends `applied: false`.	A configuration your software cannot apply stays hidden from the platform: no acknowledgement and no error, the platform only sees that `confirmed` does not arrive. The local API accepts `applied: false` and keeps it on the device (the `reason` is not stored), but does not report it, and a `connected` marker file overrides it with `applied: true`, see `applied: false`.
An old `connected` marker also confirms a new configuration.	The agent acknowledges a new configuration as soon as the marker says `connected`, even if the marker was written for the previous one. See Start your software and confirm.
SIGTERM during a check-in is tested; SIGKILL and power loss are not.	In 15 tests in a test harness with a simulated TPM, and in 3 of 3 tests on the lab gateway with the signed `cproto-v0.2.0-rc.1` (same agent source as rc.2), SIGTERM in the middle of a check-in left the stored configuration either completely the old one or completely the new one. A kill with SIGKILL or a power cut was not covered.
A leak on the raw TPM device is not healed by the agent, nor by a reboot.	At start the agent removes only its own leftover key objects, and only those visible through `/dev/tpmrm0`. A reboot of the lab gateway did not clear such a leak (measured). See TPM slots.
Memory grows slowly.	A run on the lab gateway with the signed `cproto-v0.2.0-rc.1` (same agent source as rc.2): 4.15 hours, 51 check-ins, 0 failed, PSS at most 4641 kB (within the 5.0 MB limit). The agent's own memory (`Pss_Anon`) grew by 24 kB in the 3.14 hours after the first hour: 7.6 kB per hour, 0.63 kB per check-in. In an accelerated test (aarch64 container, one check-in every 2 seconds, same source, 2011 check-ins) the growth per check-in fell over the three thirds of the run: 0.171, 0.067, 0.022 kB. The live heap stayed flat (valgrind massif) and LeakSanitizer found nothing: the growth is memory that the glibc allocator keeps in the worker thread's arena. `malloc_trim` after each check-in did not help (+68 kB instead of +72 kB over check-ins 100 to 600). Our limit of at most 2 kB per hour over the last 6 hours is not met, and was not measured on the device.
The console does not show a refused contact.	When the platform refuses a gateway's call (for example `TEMPLATE_INVALID` after the template was removed from the device), the device's pages in the console do not show it. The gateway shows it in `last_error_code` of `GET /v1/status` and in the agent's log; on the platform it is only in the service log, so support can look it up.
The current release candidate is `cproto-v0.2.0-rc.2`, and it is a candidate.	Archive, signature and checksums are published, see Download. The recipe inside this release still pins the previous candidate; the recipe in our layer pins rc.2.
No full Yocto image build with the recipe has been run.	In a test build of the package, the package check stopped at a library version tag of the curl library. See Install with Yocto and RAUC.
Not tested on a device: a real Yocto image, SIGTERM at the first setup.	Test these on your own image. The signed release archive was installed and run on the lab gateway, see Install manually.

Archive: the Go agent¶

Earlier release candidates used a Go program and a second helper, the Gateway-Agent, with several units. They are no longer part of this documentation. The branch archive/go-agent (state 936871e) is the last Go state; it contains an unpublished fix (70aded9) that was not tested on hardware. The published state is the tag v0.11.0-rc.7. The release candidates already published stay available; the C candidate cproto-v0.1.0-rc.2 carries an older set of four units and is not described here.