Rusty SunSpec Collector

Rusty SunSpec Collector is an edge service written in Rust. It finds SunSpec devices (inverters, meters, batteries) on Modbus TCP, walks each device's SunSpec model chain, polls every model on a fixed schedule and decodes the points at the edge using the official SunSpec model definitions. Samples are buffered in SQLite on local disk and published to Kafka as Avro single-object records keyed by device.

Delivery is at-least-once: a buffered sample is deleted only after Kafka acknowledges it. The buffer is bounded by row count and age, so during a very long outage the oldest samples are dropped (and counted) instead of growing the buffer without limit.

The project is a Cargo workspace of nine crates, including sunspec-sim, a SunSpec Modbus TCP simulator used by the tests and the Docker Compose stack.

flowchart LR
    subgraph field["Field"]
        devices["<b>SunSpec devices</b><br/>inverters · meters<br/>batteries"]
        serial["<b>RS-485 devices</b><br/>behind a serial<br/>converter"]
    end

    subgraph app["collector-app"]
        pollers["<b>Device pollers</b><br/>one per device<br/>discover · poll · decode"]
        buffer[("<b>SQLite buffer</b><br/>batched writes<br/>retention")]
        uplink["<b>Uplink</b><br/>Avro records<br/>at-least-once"]
        api["<b>HTTP</b><br/>/metrics · /healthz<br/>/devices · /models"]
        pollers -- "bounded<br/>channel" --> buffer --> uplink
        pollers -.-> api
    end

    devices -- "Modbus TCP" --> pollers
    serial -- "RTU over TCP" --> pollers
    uplink -- "keyed by<br/>device" --> kafka[("<b>Kafka</b>")]
    api -.-> observers["Prometheus<br/>Grafana · curl"]

    classDef external stroke-dasharray: 5 4
    class devices,serial,kafka,observers external

How data flows

1. Device set. Either a static list of hosts (discovery.static_devices) or a subnet scan (discovery.subnet, rescanned every discovery.rescan_interval_s). Each device is identified by host and Modbus unit ID, so every unit behind a gateway is polled.
2. Per-device poller. Each device runs in its own supervised task. A session connects, finds the SunS marker (configured base address first, then 40000, 0 and 50000), reads the model headers one at a time until the end marker, and then reads and decodes every model once per poll interval (or less often, for models given a slower interval in a polling profile). A failed or stalled session is restarted with exponential backoff, capped at 60 s.
3. Channel and ingest. Samples go through a bounded channel to the ingest task, which writes them to SQLite in transactions of up to 256 rows. If the channel stays full for a poll interval, the sample is dropped and counted; polling never blocks.
4. Buffer. SQLite in WAL mode. A retention task runs every 10 s and drops rows older than buffer.max_age_s (7 days) or beyond buffer.max_rows (1,000,000).
5. Uplink. The uplink reads the oldest rows in batches, publishes one Kafka record per sample and deletes only the rows Kafka acknowledged. Undelivered rows stay and are retried first.
6. Shutdown. On SIGINT or SIGTERM the pollers stop, ingest writes everything still queued, and the uplink keeps draining for up to buffer.shutdown_drain_timeout_ms (5 s). Rows that are still buffered are sent after the next start.

Each Kafka record is keyed by host/unit_id and carries the device, model ID and name, the read time, the decoded points and the raw registers. Consumers can deduplicate on (device_key, model_id, collected_at_ms). The record format is described in the README and the Avro schema; collector-app --print-schema prints the schema.

Quick start

Try it in a few minutes with simulated devices: see Quick start.

Where to go next

Known limitations

• Kafka authentication is limited to SASL PLAIN and SCRAM (no Kerberos or OAuth).
• No Schema Registry integration; records use fingerprint-based single-object encoding.
• Point units and descriptions are not in each record; they are in the model catalog (collector-app --print-models, /models).
• No configuration reload.
• Delivery is at-least-once, so duplicates are possible after a crash.

License

Dual-licensed under MIT or Apache-2.0.

Quick start

Docker Compose (no hardware needed)

docker compose up --build

This starts Kafka, a simulator with two units, the collector and Prometheus. Then:

curl localhost:9090/healthz          # 200 with a JSON body while the pipeline is running
curl -s localhost:9090/metrics | grep '^sunspec_'

Prometheus is on http://localhost:9091; Kafka is reachable from the host at localhost:29092 (topic sunspec.telemetry). docker compose down -v stops the stack and removes its volumes.

Local build

Prerequisites: Rust 1.88+, cmake and a C toolchain, pkg-config, and the OpenSSL and libcurl development headers (libssl-dev and libcurl4-openssl-dev on Debian and Ubuntu). librdkafka is built from source; SQLite and zstd are bundled.

cargo build --workspace
cargo test --workspace

# Terminal 1: simulated devices
cargo run -p sunspec-sim -- --bind 127.0.0.1:1502 --units 1,2

# Terminal 2: the collector (no Kafka configured, so each record's key and size is logged
# at debug level instead of being published)
SUNSPEC_STATIC_DEVICES=127.0.0.1:1,127.0.0.1:2 SUNSPEC_PORT=1502 \
  RUST_LOG=info,avro_kafka=debug cargo run -p collector-app

Set SUNSPEC_KAFKA_BROKERS to publish to a broker, for example localhost:29092 while the Compose stack is running.

Deployment

Deployment options

Run one collector per buffer file. Two processes on one SQLite file read the same rows, so records are published twice, and they can fail with "database is locked".

Docker

Images

Releases publish multi-arch (linux/amd64, linux/arm64) images to GHCR:

docker pull ghcr.io/imrans110/sunspec-collector:latest     # or a version, e.g. :0.5.0
docker pull ghcr.io/imrans110/sunspec-simulator:latest

To build them from source instead:

docker build -t sunspec-collector .                                 # collector (default target)
docker build --target simulator -t sunspec-simulator .              # SunSpec device simulator

The examples below use the local tag sunspec-collector; substitute ghcr.io/imrans110/sunspec-collector:<version> for a published image. The Dockerfile builds both binaries in rust:1.88-slim-bookworm and copies them into debian:bookworm-slim. The collector image:

• runs as the non-root user collector;
• runs in the working directory /app/data, so the default relative buffer path is /app/data/sunspec-buffer.sqlite. Mount a volume at /app/data. The image does not set SUNSPEC_BUFFER_PATH, so buffer.path from a config file applies; keep it relative or under /app/data so the buffer stays in the volume;
• exposes port 9090;
• has a HEALTHCHECK that runs curl -fsS "http://localhost:${SUNSPEC_METRICS_PORT:-9090}/healthz" every 30 s (3 s timeout, 20 s start period, 3 retries). It follows SUNSPEC_METRICS_PORT, but not metrics.port from a config file, so set the port with the environment variable in a container.

Run

docker run -d \
  --name sunspec-collector \
  --restart unless-stopped \
  --stop-timeout 30 \
  -p 9090:9090 \
  -e SUNSPEC_SUBNET=192.168.1.0/24 \
  -e SUNSPEC_KAFKA_BROKERS=kafka:9092 \
  -v sunspec-data:/app/data \
  sunspec-collector

--stop-timeout 30 gives the graceful shutdown the same 30 s the systemd unit allows. Docker's default is 10 s; see Graceful shutdown.

With an environment file:

docker run -d --name sunspec-collector -p 9090:9090 \
  --env-file collector.env \
  -v sunspec-data:/app/data \
  sunspec-collector

Write one VAR=value per line in environment files and put comments on their own lines. Docker's --env-file and systemd's EnvironmentFile= both keep text after # on a value line as part of the value, and the collector rejects a value such as 9090 # metrics port at startup.

To use a config file, mount it and point SUNSPEC_CONFIG at it (the image has no entrypoint, so arguments after the image name replace the command):

docker run -d --name sunspec-collector -p 9090:9090 \
  -v "$(pwd)/collector.toml:/app/collector.toml:ro" \
  -e SUNSPEC_CONFIG=/app/collector.toml \
  -v sunspec-data:/app/data \
  sunspec-collector

Check, inspect, stop

docker inspect --format='{{.State.Health.Status}}' sunspec-collector
docker logs -f sunspec-collector
docker stop sunspec-collector && docker rm sunspec-collector

Docker marks a container unhealthy when the health check fails but does not restart it. The --restart policy applies only when the process exits.

Docker Compose (local stack)

docker compose up --build starts:

curl localhost:9090/healthz
curl -s localhost:9090/metrics | grep '^sunspec_'
docker compose down -v        # stop and remove the volumes, including the buffer

The collector service has no stop_grace_period, so docker compose stop allows the default 10 s.

systemd

The unit file is sunspec-collector.service and the environment file template is sunspec-collector.env.

From a release

On x86_64 or aarch64 Linux with glibc 2.18 or newer and systemd 235 or newer (Debian 10+, Ubuntu 18.04+, RHEL 8+, Raspberry Pi OS 10+):

curl -fsSL https://github.com/imrans110/rusty-sunspec-collector/releases/latest/download/install.sh | sudo sh
sudoedit /etc/sunspec-collector.env        # devices, Kafka brokers
sudo systemctl enable --now sunspec-collector

To run without Kafka (records are then only logged), comment out the SUNSPEC_KAFKA_BROKERS line; an empty value is a configuration error.

install.sh downloads sunspec-collector-<version>-<target>.tar.gz and SHA256SUMS from the release, checks the archive's checksum, and installs:

It runs systemctl daemon-reload but does not start or restart the service; after an upgrade, run sudo systemctl restart sunspec-collector. SUNSPEC_VERSION=0.5.0 installs a specific release. To read the script first: curl -fsSLO <url>, read install.sh, then sudo sh install.sh. From 0.5.0 the release files and images are attested, so a downloaded install.sh, archive or SHA256SUMS can be checked with gh attestation verify first; see Verifying a release.

To install from a downloaded archive by hand, use the archive's files in the steps below instead of building.

From source

# 1. Build the release binary (see Building & Packaging) and install it
cargo build --release -p collector-app
sudo install -m 0755 target/release/collector-app /usr/local/bin/collector-app

# 2. Install the unit and the environment file, then edit the environment file
sudo install -m 0644 docs/sunspec-collector.service /etc/systemd/system/sunspec-collector.service
sudo install -m 0644 docs/sunspec-collector.env /etc/sunspec-collector.env
sudoedit /etc/sunspec-collector.env

# 3. Optional: a config file, enabled with SUNSPEC_CONFIG=/etc/sunspec-collector.toml
#    in the environment file
sudo install -m 0644 docs/config.example.toml /etc/sunspec-collector.toml

# 4. Start it
sudo systemctl daemon-reload
sudo systemctl enable --now sunspec-collector
systemctl status sunspec-collector

Do not create /var/lib/sunspec-collector yourself; systemd creates and owns it (see below).

Keep SUNSPEC_BUFFER_PATH=/var/lib/sunspec-collector/buffer.sqlite in the environment file. The unit sets no working directory and the file system is read-only to the service except for its state directory, so the default relative buffer path fails with buffer init failed.

The service reads the config file as an unprivileged dynamic user, so the file must be world-readable (mode 0644) and must not be under /home (ProtectHome=true). systemd reads the environment file itself, before dropping privileges.

What the unit does

ExecStart passes no arguments. Use SUNSPEC_CONFIG in the environment file, or a drop-in (systemctl edit sunspec-collector), to change how the binary is started.

Logs

journalctl -u sunspec-collector -n 200 --no-pager     # recent logs
journalctl -u sunspec-collector -f                    # follow
journalctl -u sunspec-collector -p warning --no-pager # warnings and errors only

Graceful shutdown

SIGINT (Ctrl-C) and SIGTERM (sent by systemctl stop and docker stop) start a graceful stop:

1. The log shows shutdown signal received. Device pollers stop; reads in progress are abandoned. Pollers get 10 s to finish before they are aborted.
2. The ingest task writes every sample still queued in the channel to SQLite, then logs ingest stopped.
3. The uplink finishes the batch it is publishing, then keeps draining the buffer for up to buffer.shutdown_drain_timeout_ms (default 5 s; 0 skips this step). If time runs out, it logs final uplink drain timed out; remaining rows stay buffered for the next start.
4. Retention, the HTTP server and the watchdog stop. The log shows collector stopped and the process exits with status 0.

Rows left in the buffer are published after the next start.

A stop normally takes a few seconds. The worst case is roughly the 10 s poller grace, plus one in-flight batch (up to kafka.timeout_ms), plus buffer.shutdown_drain_timeout_ms. The systemd unit allows 30 s (TimeoutStopSec). Docker allows 10 s unless you pass --stop-timeout (or set stop_grace_period in Compose). If you raise buffer.shutdown_drain_timeout_ms, raise these limits too.

If the process is killed instead (SIGKILL, power loss):

• rows already committed to SQLite are kept and sent after the restart;
• samples still in the channel, not yet written, are lost;
• rows that Kafka acknowledged but that were not yet deleted are sent again, so consumers see duplicates. See Delivery semantics.

Logs

Logs go to standard output (journald under systemd, docker logs in Docker). Set the level with RUST_LOG (default info) and the format with SUNSPEC_LOG_FORMAT=text|json; see Logging. At info, steady-state operation logs almost nothing: per-cycle and per-batch messages are at debug level.

Messages worth knowing:

librdkafka's own log lines use the librdkafka target. Its connection failures while a broker is down (for example Connect to ipv4#... failed) are at debug, since the outage warning above covers them.

Securing the Kafka connection

The collector supports TLS, mutual TLS and SASL (PLAIN, SCRAM-SHA-256, SCRAM-SHA-512); the keys are listed in Configuration. Use sasl_ssl or ssl whenever the traffic leaves the site: sasl_plaintext sends the password and the telemetry unencrypted, and the collector logs a warning when it is used.

SCRAM over TLS, with the password in a file:

[kafka]
brokers = "kafka-1.example.com:9093,kafka-2.example.com:9093"
security_protocol = "sasl_ssl"
ssl_ca_location = "/etc/sunspec-collector/kafka-ca.pem"
sasl_mechanism = "SCRAM-SHA-512"
sasl_username = "site-0042"
sasl_password_file = "/run/credentials/sunspec-collector.service/kafka-password"

Mutual TLS instead of SASL: set security_protocol = "ssl", ssl_ca_location, ssl_certificate_location and ssl_key_location (plus ssl_key_password_file if the key is encrypted).

Keeping secrets out of config and environment files

Prefer the *_password_file settings over putting passwords in the config file or environment:

• systemd: store the password root-only on the host and pass it as a credential. Add to the unit (or a drop-in from systemctl edit sunspec-collector):

  [Service]
  LoadCredential=kafka-password:/etc/sunspec-collector/kafka-password
  Environment=SUNSPEC_KAFKA_SASL_PASSWORD_FILE=/run/credentials/sunspec-collector.service/kafka-password
  

  The file is readable only by the service, which also works with DynamicUser=yes.

• Docker / Compose: mount the password as a secret and point the _FILE variable at it, as the local stack does:

  services:
    collector:
      environment:
        SUNSPEC_KAFKA_SASL_PASSWORD_FILE: /run/secrets/kafka_sasl_password
      secrets:
        - kafka_sasl_password
  secrets:
    kafka_sasl_password:
      file: ./kafka-sasl-password
  

  The secret file must be readable by the container user (collector).

The compose stack's password (docker/dev-secrets/) is a development-only value.

Rotating credentials

Certificates, keys and passwords are read when the collector starts. After rotating them, restart the service (systemctl restart sunspec-collector or docker compose restart collector). Unsent samples stay in the buffer and are published after the restart.

Serial devices through a converter

Many inverters and meters only have an RS-485 port. A serial-to-Ethernet converter in transparent mode (often called "TCP server", "raw" or "transparent"; not "Modbus TCP gateway") passes Modbus RTU frames between a TCP connection and the bus unchanged. Set the framing to rtu and list each unit on the bus:

[modbus]
port = 8899                       # the converter's TCP port

[[discovery.static_devices]]
ip = "192.168.1.60"               # the converter
unit_id = 1
framing = "rtu"

[[discovery.static_devices]]
ip = "192.168.1.60"
unit_id = 2
framing = "rtu"

([modbus] framing = "rtu" applies it to every device instead, and SUNSPEC_MODBUS_FRAMING=rtu does the same from the environment.)

• RTU has no transaction IDs, so only one request may be on the bus at a time. All units on the same converter (host and port) share one TCP connection, and their requests run one after another. Per-device poll intervals and model settings may differ, but request_timeout_ms and max_batch_size must match; validation says so if they do not.
• Serial buses are slow: 125 registers at 9600 baud take roughly 300 ms. Raise poller.request_timeout_ms and, if the converter buffers little, lower modbus.max_batch_size. A slow or absent unit delays the others, because they wait for the bus.
• A unit that does not answer times out. The connection is then reopened (a late reply could otherwise be read as the answer to the next request), so an absent unit on a shared converter causes reconnects for its neighbours; remove units that are not on the bus.
• If the converter is in "Modbus TCP gateway" mode instead, it translates Modbus TCP to RTU itself: keep the default framing = "tcp".
• collector-app --probe uses the same framing, so it works through the converter too.

Native serial ports (a USB RS-485 adapter on the gateway) are not supported yet.

Polling profiles

By default every discovered model is read on every poll cycle. Models that rarely change, such as common (1), nameplate (120) and settings (121), can be read less often, and models you do not need can be skipped. Both cut Modbus traffic and Kafka volume.

[poller]
poll_interval_ms = 1000
exclude_models = [123]            # never read the immediate controls model

[poller.model_intervals_s]        # model ID = seconds
1 = 3600                          # common: hourly
120 = 3600                        # nameplate: hourly
121 = 600                         # settings: every 10 minutes

The same in the environment (for the systemd environment file or Docker):

SUNSPEC_MODEL_INTERVALS_S=1=3600,120=3600,121=600
SUNSPEC_EXCLUDE_MODELS=123

How the schedule works:

• Every polled model is read on the first cycle of a session, so a device's identity and settings are published as soon as it connects. After a successful read, a model with an interval is read again on the first cycle at least that long later. A failed read is retried on the next cycle.
• Intervals are counted in whole poll cycles: with poll_interval_ms = 1000, 121 = 600 reads model 121 every 600th cycle.
• A new session (after a reconnect, a stall or repeated failures) reads every model again, so a slow model can be read more often than its interval while a device is unstable.
• A cycle in which nothing is due does not contact the device and does not count towards the stall timeout.
• include_models and exclude_models filter the discovered chain. Listing a model that a device does not have is not an error. If nothing on a device is selected, its session ends with none of the discovered models [...] is selected for polling and is retried with the usual backoff; the chain is rediscovered each time, so a firmware update that adds a model is noticed.
• Discovery still reads every model header. The discovered SunSpec models log line lists the whole chain (models), the models that are polled (polled) and the slow ones (slow).

Per-device settings

A [[discovery.static_devices]] entry in a config file can override these settings for that device:

[poller.model_intervals_s]
1 = 3600
120 = 3600

[[discovery.static_devices]]
ip = "192.168.1.30"               # a slow meter behind a serial gateway
unit_id = 2
poll_interval_ms = 5000
request_timeout_ms = 3000
max_batch_size = 60

[[discovery.static_devices]]
ip = "192.168.1.40"               # an inverter at unit 126 with MPPT data every 10 s
unit_id = 126
include_models = [1, 120, 160]
model_intervals_s = { 1 = 86400, 160 = 10 }   # merged: 1 daily, 120 hourly, 160 every 10 s

• Per-device settings exist only in the config file. SUNSPEC_STATIC_DEVICES replaces the file's device list together with these settings, and logs a warning when it does.
• Devices found by a subnet scan use the global settings.
• After its overrides are applied, a device's include_models and exclude_models may not share a model; the error names the device.

Probing a device

collector-app --probe HOST[:UNIT] reads one device's SunSpec map once and prints it as JSON: the base address, every model's header address and length, its registers, and the decoded points. It uses the same settings as the service (--config, SUNSPEC_* variables, and the device's static-device overrides), so it shows what the collector would read, and it does not start the service.

collector-app --probe 192.168.1.50:126 > dump.json
SUNSPEC_PORT=1502 collector-app --probe inverter.local          # unit defaults to 1

The JSON goes to standard output and a one-line summary to standard error, for example 192.168.1.50/126: SunSpec map at 40000, models 1, 103, 120, 160. A model that cannot be read is kept in the dump with its error, and named in a warning. Serial numbers (SN) and network addresses (MAC, IPv4, IPv6) in each model's top level are blanked and listed under redacted; --keep-identifiers keeps them.

Use it when commissioning a device, when a device is not polled (it shows whether the SunSpec map is found and every model reads), and for device reports. sunspec-sim --fixture dump.json serves the dump again, so a reported problem can be reproduced without the hardware (see fixtures/devices/README.md).

Verifying a release

From 0.5.0, each release's archives, install.sh and SHA256SUMS, and both images, carry SLSA build provenance: a statement of the workflow run, commit and tag that built them, signed with a short-lived Sigstore certificate issued to release.yml and recorded in Sigstore's public transparency log. GitHub artifact attestations are free for public repositories. To check a download with the GitHub CLI:

gh attestation verify sunspec-collector-0.5.0-x86_64-unknown-linux-gnu.tar.gz \
  --repo imrans110/rusty-sunspec-collector \
  --signer-workflow imrans110/rusty-sunspec-collector/.github/workflows/release.yml \
  --source-ref refs/tags/v0.5.0
gh attestation verify oci://ghcr.io/imrans110/sunspec-collector:0.5.0 \
  --repo imrans110/rusty-sunspec-collector

gh finds the attestation by the file's or image's digest. The release also has the signed bundle, sunspec-collector-<version>.intoto.jsonl; --bundle <file> verifies against it instead of looking the attestation up on GitHub. Verifying SHA256SUMS once covers every archive it lists, so install.sh's checksum check then ties the installed archive to the attested build.

Monitoring and alerts

How to scrape the collector with Prometheus and which alerts to start with. Every metric is described in Metrics.

Scrape configuration

scrape_configs:
  - job_name: sunspec-collector
    static_configs:
      - targets: ["collector-host:9090"]

The Compose stack uses the same configuration in docker/prometheus.yml.

Recommended alert rules

groups:
  - name: sunspec-collector
    rules:
      - alert: SunspecCollectorDown
        expr: up{job="sunspec-collector"} == 0
        for: 2m
        labels:
          severity: critical
        annotations:
          summary: "Prometheus cannot scrape the collector on {{ $labels.instance }}"

      - alert: SunspecDeviceDown
        expr: sunspec_device_up == 0
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "Device {{ $labels.device }} has not been polled successfully for 5 minutes"

      # Devices whose sessions keep failing, including ones that flap between up and down.
      - alert: SunspecDeviceRestarting
        expr: increase(sunspec_poller_restarts_total[15m]) >= 5
        labels:
          severity: warning
        annotations:
          summary: "Device {{ $labels.device }} sessions keep failing"

      - alert: SunspecPollerStalled
        expr: increase(sunspec_poller_stalls_total[15m]) > 0
        labels:
          severity: warning
        annotations:
          summary: "Device {{ $labels.device }} stalled and was restarted"

      - alert: SunspecSamplesDropped
        expr: increase(sunspec_samples_dropped_total[15m]) > 0
        labels:
          severity: warning
        annotations:
          summary: "Samples dropped before the buffer ({{ $labels.reason }})"

      - alert: SunspecUplinkErrors
        expr: increase(sunspec_uplink_errors_total[10m]) > 0
        labels:
          severity: warning
        annotations:
          summary: "Kafka is not acknowledging records from {{ $labels.instance }}"

      # Rows are waiting but nothing was delivered in the last 5 minutes (also fires when
      # nothing has been delivered since startup, when the counter does not exist yet).
      - alert: SunspecUplinkStalled
        expr: (sunspec_buffer_rows > 0) unless (rate(sunspec_uplink_records_total[5m]) > 0)
        for: 10m
        labels:
          severity: critical
        annotations:
          summary: "No records delivered to Kafka from {{ $labels.instance }}"

      - alert: SunspecBufferBacklog
        expr: sunspec_buffer_oldest_age_seconds > 600
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "Oldest buffered row is {{ $value | humanizeDuration }} old"

      - alert: SunspecBufferDataLoss
        expr: increase(sunspec_buffer_dropped_total[1h]) > 0
        labels:
          severity: critical
        annotations:
          summary: "Buffered data dropped without being published ({{ $labels.reason }})"

To alert on /healthz itself, probe it with the Prometheus blackbox exporter (an http_2xx module) and alert on the probe:

      - alert: SunspecCollectorUnhealthy
        expr: probe_success{job="sunspec-healthz"} == 0
        for: 5m
        labels:
          severity: critical

Buffer Maintenance

The collector writes every sample to a local SQLite database before it publishes anything to Kafka. This page describes what is in that database, how rows move through it, how to size it, and how to inspect and maintain it safely.

Settings referred to here are described in Configuration; metrics are in Metrics and alerts in Monitoring and alerts.

What the buffer is for

Pollers produce samples on a fixed schedule whether or not Kafka is reachable. The buffer decouples the two:

pollers → channel → ingest → SQLite buffer → uplink → Kafka

• Ingest writes samples to SQLite in transactions of up to 256 rows: samples that arrive within 100 ms of the first one share one transaction and one fsync.
• Uplink reads the oldest rows, publishes them, and deletes them once Kafka has acknowledged them.
• Retention runs every 10 s and keeps the buffer within buffer.max_rows and buffer.max_age_s.

During a Kafka or network outage the rows wait on disk and are sent when Kafka is reachable again. The buffer also survives collector restarts.

Where it lives

The path is set with buffer.path / SUNSPEC_BUFFER_PATH. The file is created if it does not exist, and the table and index are created at startup.

SQLite keeps three files side by side, named after the database file (here the systemd name buffer.sqlite; in Docker by default sunspec-buffer.sqlite, sunspec-buffer.sqlite-wal and sunspec-buffer.sqlite-shm):

Treat the three files as one unit: copy, move or delete them together, and only while the collector is stopped.

Schema

CREATE TABLE telemetry_queue (
    id         INTEGER PRIMARY KEY AUTOINCREMENT,
    topic      TEXT    NOT NULL,
    payload    BLOB    NOT NULL,
    created_at INTEGER NOT NULL
);
CREATE INDEX idx_created_at ON telemetry_queue(created_at);

A payload looks like this (registers and points shortened):

{
  "device": {"ip": "192.168.1.20", "unit_id": 1},
  "model_id": 103,
  "model_name": "inverter_three_phase",
  "start": 40070,
  "registers": [103, 50, 769, 0, 0, 0, 65534, ...],
  "collected_at_ms": 1792212700844,
  "points": [["A", 7.69], ["AphA", 0.0], ..., ["PhVphA", 230.3], ["W", 5309.0], ["Hz", 50.02], ["St", 4]]
}

• start is the register address of the model header; registers are the raw values, including the two header registers.
• collected_at_ms is the time the model was read. It differs from created_at, which is when the row was written.
• points are the decoded points as [name, value] pairs in definition order. A value is a number, a string or null (not implemented). Models without a bundled definition have an empty list. Rows written by earlier versions have no points field and are published with an empty points map.

SQLite settings

• WAL journal mode. Readers and the writer do not block each other, so the uplink can read while ingest writes, and a sqlite3 session can read while the collector runs. Writes (ingest inserts, uplink and retention deletes) still take turns.
• synchronous=NORMAL, set on every connection. A committed transaction survives a crash or kill of the collector process. After a power loss or an operating-system crash, the most recent transactions can be rolled back; the database itself stays consistent.
• SQLite checkpoints the WAL into the main file automatically, by default every 1000 pages (about 4 MB with the default 4 KB page size), and reuses the WAL file afterwards.

Delivery semantics

Delivery is at-least-once.

1. The uplink reads up to buffer.batch_size rows, oldest first.
2. Each row becomes one Kafka record, keyed by device_key (host/unit). All records of the batch are handed to the producer, then the uplink waits for the acknowledgements.
3. Rows that Kafka acknowledged are deleted.
4. Rows that Kafka did not acknowledge within kafka.timeout_ms stay in the buffer. They are still the oldest rows, so they are retried first. Failed records count in sunspec_uplink_errors_total. After a batch in which nothing was delivered, the uplink backs off (1 s, doubling, up to 30 s). If the records timed out while broker connections were failing, it asks the brokers every 2 s during the backoff whether they answer, and ends the backoff as soon as they do.
5. Rows that can never be published (the payload is not valid JSON, or the sample cannot be encoded as Avro) are deleted, logged, and counted in sunspec_buffer_dropped_total{reason="corrupt"}, so they cannot block the queue.

While a backlog exists, the uplink drains batch after batch without pausing. It waits buffer.drain_interval_ms only after a batch that was not full.

Duplicates are possible. If the process dies after Kafka acknowledged a batch but before the rows were deleted, or if the delete fails (logged as deleting published rows failed; they may be sent again), those rows are sent again. Consumers can deduplicate on (device_key, model_id, collected_at_ms).

Records are sent oldest first, but a record that fails and is retried can arrive after newer records. Consumers should order by collected_at_ms, not by arrival.

Without kafka.brokers, the uplink hands records to a log-only sink, which counts as delivered: rows are deleted and nothing is kept.

Retention

The retention task runs at startup and then every 10 s:

1. Deletes rows whose created_at is older than buffer.max_age_s (default 604800 s, 7 days). Counted in sunspec_buffer_dropped_total{reason="max_age"}.
2. Deletes the oldest rows beyond buffer.max_rows (default 1,000,000). Counted in sunspec_buffer_dropped_total{reason="max_rows"}.
3. Updates sunspec_buffer_rows and sunspec_buffer_oldest_age_seconds.

Both deletions log a warning with the number of rows dropped. Rows dropped by retention are lost.

Because retention runs every 10 s, the buffer can briefly exceed max_rows by up to 10 s of writes. Because it runs at startup, rows older than max_age_s are deleted when a collector starts after a long stop, before the uplink can send them.

Samples that never reach the buffer are counted separately: sunspec_samples_dropped_total{reason="channel_full"} (ingest too slow) and sunspec_buffer_dropped_total{reason="write_error"} (an SQLite write failed, for example on a full disk).

Sizing

Rows per second

Every polled model of every device produces one row per poll interval, and a model with a polling profile interval one row per interval:

rows per second = devices × (models polled every cycle ÷ poll interval in seconds
                             + Σ 1 ÷ slow model interval in seconds)

The discovered SunSpec models log line lists each device's models, the ones it polls and the slow ones. For example, a device with models 1, 103, 120, 121 and 160, polled every second with 1 and 120 hourly and 121 every 10 minutes, produces about 2 rows per second instead of 5.

Bytes per row

Row size depends on the models. As a rough upper estimate:

payload bytes ≈ 150 + 5 × registers + 15 × decoded points
bytes on disk ≈ payload bytes + about 120 (row header, topic, timestamp, index entry)

For reference, with the simulator's models 1, 103, 120 and 160 the payloads were 436–718 bytes (about 580 on average) and the database file grew by about 0.7 KB per row. Rows from real devices can be larger, because values with more digits take more bytes in JSON. To measure your own rows, see Inspecting the buffer.

Example

10 inverters × 4 models, polled every second, at about 0.7 KB per row:

With these numbers the default max_rows is reached long before the default max_age_s of 7 days. Pick the outage you want to ride out, then:

max_rows   ≥ rows per second × outage seconds
disk space ≥ max_rows × bytes on disk + headroom for the WAL and for VACUUM (see below)

The database file does not shrink when rows are deleted. SQLite reuses the freed pages, so after a large backlog has drained the file keeps its largest size until it is vacuumed.

Inspecting the buffer

Use the sqlite3 command-line tool (apt install sqlite3 on Debian and Ubuntu). The Docker image does not include it.

While the collector is running, open the database read-only and keep sessions short. A session left open holds a read snapshot that stops SQLite from checkpointing the WAL, so the WAL file grows. -readonly fails with unable to open database file when the -wal and -shm files do not exist; in that case stop the collector and follow Safe maintenance.

systemd (root is needed to enter /var/lib/private):

sudo sqlite3 -readonly /var/lib/sunspec-collector/buffer.sqlite

Docker, from a throwaway container that mounts the same volume:

docker run --rm -it -v sunspec-data:/data debian:bookworm-slim sh -c \
  'apt-get update -qq && apt-get install -y -qq sqlite3 >/dev/null && sqlite3 -readonly /data/sunspec-buffer.sqlite'

The examples use the Docker default file name. If you set buffer.path or SUNSPEC_BUFFER_PATH (for example /app/data/buffer.sqlite), use the matching name under /data.

The queries below can be typed at the sqlite3> prompt, or passed on standard input:

sudo sqlite3 -readonly /var/lib/sunspec-collector/buffer.sqlite <<'SQL'
SELECT COUNT(*) FROM telemetry_queue;
SQL

Rows waiting:

SELECT COUNT(*) AS rows FROM telemetry_queue;

Age of the oldest row (the same value as sunspec_buffer_oldest_age_seconds):

SELECT datetime(MIN(created_at) / 1000, 'unixepoch') AS oldest_written_utc,
       round((CAST(strftime('%s', 'now') AS INTEGER) * 1000 - MIN(created_at)) / 1000.0, 1) AS oldest_age_s
FROM telemetry_queue;

Rows per device and model:

SELECT json_extract(CAST(payload AS TEXT), '$.device.ip') || '/' ||
       json_extract(CAST(payload AS TEXT), '$.device.unit_id') AS device,
       json_extract(CAST(payload AS TEXT), '$.model_id') AS model_id,
       COUNT(*) AS rows
FROM telemetry_queue
GROUP BY device, model_id
ORDER BY device, model_id;

The oldest rows, and one payload:

SELECT id, datetime(created_at / 1000, 'unixepoch') AS written_utc, length(payload) AS bytes
FROM telemetry_queue ORDER BY id LIMIT 5;

SELECT CAST(payload AS TEXT) FROM telemetry_queue ORDER BY id LIMIT 1;

Average row size and file usage, for sizing:

SELECT COUNT(*) AS rows, round(avg(length(payload))) AS avg_payload_bytes FROM telemetry_queue;

SELECT page_count * page_size AS file_bytes, freelist_count * page_size AS free_bytes
FROM pragma_page_count(), pragma_page_size(), pragma_freelist_count();

CAST(payload AS TEXT) makes the JSON functions treat the BLOB as text JSON on every SQLite version.

Safe maintenance

Stop the collector before changing the buffer. Reading is safe while it runs; anything that writes (VACUUM, DELETE, replacing the file) should be done with the service stopped.

sudo systemctl stop sunspec-collector     # systemd
docker stop sunspec-collector             # Docker

Commands run as root can leave a root-owned -wal or -shm file behind, which the service user then cannot open. Each procedure below ends by giving the files back to the owner of the directory.

Reclaim disk space (VACUUM)

Routine vacuuming is not needed: SQLite reuses freed pages. Vacuum when a large backlog has drained and you want the disk space back. VACUUM rewrites the whole database and needs free space of about twice the database size.

Do not vacuum while the collector is running. VACUUM holds an exclusive lock for its whole run; the collector's writes wait for a few seconds and then fail, and the samples in them are dropped (reason="write_error").

systemd:

sudo systemctl stop sunspec-collector
sudo sqlite3 /var/lib/sunspec-collector/buffer.sqlite 'VACUUM; PRAGMA wal_checkpoint(TRUNCATE);'
sudo sh -c 'chown --reference=/var/lib/sunspec-collector /var/lib/sunspec-collector/*'
sudo systemctl start sunspec-collector

Docker:

docker stop sunspec-collector
docker run --rm -v sunspec-data:/data debian:bookworm-slim sh -c '
  apt-get update -qq && apt-get install -y -qq sqlite3 >/dev/null &&
  sqlite3 /data/sunspec-buffer.sqlite "VACUUM; PRAGMA wal_checkpoint(TRUNCATE);" &&
  chown --reference=/data /data/*'
docker start sunspec-collector

Earlier versions of this guide suggested a weekly systemd timer that vacuumed the live database. Remove such a timer, or make it stop the service first, for the reason above.

Discard part of the backlog

Deleted rows are never published. With the collector stopped:

-- Rows written more than 24 hours ago
DELETE FROM telemetry_queue WHERE created_at < (CAST(strftime('%s', 'now') AS INTEGER) - 86400) * 1000;

-- All rows of one device
DELETE FROM telemetry_queue
WHERE json_extract(CAST(payload AS TEXT), '$.device.ip') = '192.168.1.20'
  AND json_extract(CAST(payload AS TEXT), '$.device.unit_id') = 1;

Then restore ownership as shown above and start the collector.

Delete the buffer

Deleting the buffer loses every sample that has not been published. With the collector stopped, delete the database file and its -wal and -shm files together (for example buffer.sqlite, buffer.sqlite-wal and buffer.sqlite-shm); the collector creates an empty buffer at the next start. Never delete only the -wal file: it can hold committed rows that are not yet in the main file.

Back up

A buffer backup is rarely needed, since its rows are meant to be short-lived. If you need one:

• While running: use SQLite's online backup, which produces a consistent copy:

  sudo sqlite3 -readonly /var/lib/sunspec-collector/buffer.sqlite ".backup '/root/buffer-backup.sqlite'"
  

• While stopped: copy all three files.

Restoring a backup (collector stopped, old files removed, ownership restored) re-sends every row in it, including rows that were delivered after the backup was taken. Consumers see duplicates.

Recovery after a long outage

While Kafka is unreachable:

• the uplink retries the oldest batch with backoff (1 s doubling to 30 s), and each attempt waits up to kafka.timeout_ms for acknowledgements. sunspec_uplink_errors_total increases with each attempt, and each attempt logs records not delivered; they stay buffered. librdkafka's reconnect attempts are logged at warn at most once per 5 minutes (Kafka broker connection failed);
• polling and ingest carry on, so sunspec_buffer_rows and sunspec_buffer_oldest_age_seconds rise;
• once the limits are reached, retention drops the oldest rows (sunspec_buffer_dropped_total{reason="max_rows"|"max_age"});
• /healthz stays 200, because the pipeline itself is working.

When Kafka is reachable again:

1. The uplink asks the brokers every 2 s whether they are back, so it starts draining within about 2 s of them answering rather than waiting out the rest of a 30 s backoff, and logs records delivered again. It then drains back to back while the batches come back full. It pauses for buffer.drain_interval_ms only once a batch is not full, that is, when the backlog is gone.

2. Rows are sent oldest first, so the newest data arrives last. Consumers receive records with old collected_at_ms values for a while.

3. Watch sunspec_buffer_rows and sunspec_buffer_oldest_age_seconds fall. The drain only makes progress while delivery is faster than intake:

   rate(sunspec_uplink_records_total[5m]) - rate(sunspec_buffer_writes_total[5m])
   

   The remaining time in seconds is roughly:

   sunspec_buffer_rows
     / (rate(sunspec_uplink_records_total[5m]) - rate(sunspec_buffer_writes_total[5m]))
   

4. To drain faster, raise buffer.batch_size (for example to 500 or 1000) and restart the collector; buffered rows are kept across the restart. Each batch waits for the producer's 50 ms linger plus the broker round trip, so larger batches mean fewer waits. One batch is held in memory at a time.

5. Data that retention dropped during the outage is gone; sunspec_buffer_dropped_total shows how many rows.

6. After the backlog has drained, the database file keeps its largest size. Vacuum it if you need the disk space back.

Do not delete the buffer to catch up faster unless you intend to discard the backlog.

Troubleshooting

Startup errors

A wrong setting stops the collector with exit status 78. Under systemd the service then stays failed instead of restarting: systemctl status sunspec-collector shows status=78, and journalctl -u sunspec-collector -n 20 shows the error. Fix the setting, then run systemctl restart sunspec-collector. Other startup errors exit with status 1, and systemd keeps retrying every 5 s.

Serial devices through a converter

See Serial devices through a converter.

Probing a device

See Probing a device.

A device is not polled

1. Check that the collector knows the device: curl localhost:9090/devices lists every supervised device with its state and latest readings; sunspec_devices_known, devices_total in /healthz, and a starting device poller device=host/unit log line say the same. In subnet mode the host must accept a TCP connection on the Modbus port within discovery.per_host_timeout_ms.
2. Check sunspec_device_up{device="host/unit"}. A value of 0 means the device is not being read successfully; if sunspec_device_last_success_timestamp_seconds has no series for it, it has not been read successfully since the collector started. If sunspec_poller_restarts_total keeps increasing, its sessions keep failing; sunspec_poll_errors_total{kind} shows whether connects or reads fail.
3. Find the reason in the logs: journalctl -u sunspec-collector | grep 'device session ended', or probe the device directly with collector-app --probe host:unit (see Probing a device).

If discovery reports (last answer: Gateway target device failed to respond), or the modbus read failed lines before a session ends show that exception, a gateway answered but has no device at that unit ID. Check the unit IDs. Each failed attempt before a retry is logged at debug (RUST_LOG=info,modbus_client=debug).

Failed sessions are retried with exponential backoff capped at 60 s, so a device that comes back online is picked up within about a minute without restarting the collector.

No records in Kafka

1. Check that kafka.brokers / SUNSPEC_KAFKA_BROKERS is set. Without it, records are only logged at debug level (record published (log sink) with RUST_LOG=info,avro_kafka=debug) and then removed from the buffer.
2. Check sunspec_uplink_errors_total and the records not delivered; they stay buffered log line. Rising errors mean the brokers are unreachable or are rejecting the records (wrong address, missing topic with auto-creation disabled, ACLs, or a security mismatch). Kafka broker connection failed gives librdkafka's reason, naming the broker; it is logged at warn at most once per 5 minutes, and every attempt at debug (RUST_LOG=info,avro_kafka=debug). records delivered again marks the end of an outage. Authentication problems show up as Kafka client error with SASL authentication error or SSL handshake failed. Check kafka.security_protocol, the SASL mechanism and credentials, and that kafka.ssl_ca_location holds the CA that signed the broker certificate.
3. Check sunspec_buffer_oldest_age_seconds and sunspec_buffer_rows. If they grow while sunspec_uplink_records_total is flat, nothing is being delivered.
4. If records arrive but consumers fail to read them, the consumers may still expect the old format; see Upgrade notes.

The buffer keeps growing

The buffer grows when samples are written faster than they are delivered. Compare:

rate(sunspec_buffer_writes_total[5m])     # samples in
rate(sunspec_uplink_records_total[5m])    # records out

• Kafka down or rejecting records: see the previous section. The buffer holds the data until retention starts dropping it (sunspec_buffer_dropped_total{reason="max_rows"|"max_age"}).
• Kafka up but slow: check sunspec_uplink_publish_seconds. Each batch waits for the producer's 50 ms linger plus the broker round trip, so a larger buffer.batch_size raises throughput.
• More data than expected: every polled model of every device produces one row per poll interval. Read slow-changing models less often or skip unneeded ones with a polling profile; see also Sizing.

Stalls

sunspec_poller_stalls_total increases when a session goes poller.stall_timeout_ms (default max(10 × poll interval, 30 s)) without a successful read. This usually means every read of the device timed out or failed for that long, for example when a device keeps its TCP connection open but stops answering. The session is ended and retried with backoff. The modbus read failed lines for the device show the errors. Occasional stalls point to the device, the gateway or the network; a device that stalls repeatedly also triggers the SunspecDeviceRestarting alert.

If /healthz returns 503, the ingest task or the uplink itself has stopped checking in. That is a collector problem rather than a device problem; the systemd watchdog restarts the service. Keep the logs from before the restart.

Samples dropped with reason="channel_full"

The ingest task could not take a sample within one poll interval, usually because SQLite writes are slow (slow or failing storage). Check disk health and latency. runtime.channel_capacity absorbs short bursts but does not fix slow storage.

Poll cycles take longer than the poll interval

Compare sunspec_poll_duration_seconds with poller.poll_interval_ms. When a cycle overruns, the next tick is skipped, so samples arrive less often than configured. Increase the poll interval, or reduce per-request latency (lower poller.request_timeout_ms, fewer retries).

"database is locked"

Two collectors are using the same buffer file, or a manual sqlite3 session holds a write lock. Run one collector per buffer file and follow Buffer Maintenance for manual work.

Upgrade notes for this release

This release contains breaking changes. Read all of this section before upgrading.

Kafka record format v2 (breaking)

collector-app --print-schema prints the v2 schema; Rust consumers can use avro_kafka::decode. Consumers must be updated before or together with the collector. To avoid mixing formats on one topic, consider publishing v2 to a new topic (kafka.topic).

Schema 2.1: labels

Schema 2.1 adds a labels map (enum values and set bitfield bits by name) with an empty default. Avro readers resolve old and new records with either schema, but the schema's fingerprint changes. Consumers that look up the writer schema by fingerprint need the 2.1 schema (collector-app --print-schema) before they read records from this version.

Rows buffered by the previous version are published in the v2 format after the upgrade, but with an empty points map and the old model names. To avoid this, let the old version drain its buffer (buffer_size at 0) before you upgrade.

Expect more records per device than before. Models beyond the first 200 registers are now found by walking the model chain, and every unit ID behind a gateway is polled (previously only one unit per host was).

Metric renames (breaking)

Update dashboards and alerts:

New metrics: sunspec_poll_duration_seconds, sunspec_device_up, sunspec_device_last_success_timestamp_seconds, sunspec_poller_restarts_total, sunspec_poller_stalls_total, sunspec_devices_known, sunspec_samples_dropped_total, sunspec_buffer_dropped_total, sunspec_buffer_oldest_age_seconds.

Strict configuration (breaking)

Unknown keys, unparsable environment values, invalid static devices, unsupported kafka.compression / kafka.acks values, kafka.acks of 0 or 1 with idempotence enabled, and modbus.max_batch_size above 125 now stop the collector at startup instead of being ignored or adjusted. Before upgrading, compare your config file with the reference and check your environment file for inline comments and empty values.

Deprecated settings

Accepted, ignored, and logged with a warning:

• sunspec.discovery_register_count / SUNSPEC_DISCOVERY_REG_COUNT: models are found by walking the model chain.
• modbus.timeout_ms / SUNSPEC_MODBUS_TIMEOUT_MS: use poller.request_timeout_ms / SUNSPEC_REQUEST_TIMEOUT_MS.

Deployment changes

• systemd: the unit now runs as a dynamic unprivileged user with StateDirectory=sunspec-collector, Type=notify with a health-gated watchdog, and TimeoutStopSec=30. Install the new unit file and run systemctl daemon-reload. The previous guide had you create /var/lib/sunspec-collector as root; after the first start with the new unit, check that the log shows buffer initialized and no write errors.
• Docker: the HEALTHCHECK now calls /healthz instead of /metrics, on the port in SUNSPEC_METRICS_PORT (default 9090). The image's working directory is /app/data, so without SUNSPEC_BUFFER_PATH or buffer.path the buffer is /app/data/sunspec-buffer.sqlite. Deployments that set SUNSPEC_BUFFER_PATH=/app/data/buffer.sqlite, as the previous guide and Compose file did, keep using that file.
• A metrics port that cannot be bound now stops the collector at startup instead of leaving it running without /metrics and /healthz.
• SIGTERM now takes the graceful shutdown path.

Upgrade procedure

1. Update Kafka consumers to read v2 records (or prepare a new topic).
2. Let the old collector drain its buffer, then stop it.
3. Install the new binary or image, the new unit file and an updated config / environment file.
4. Start the collector and check /healthz, sunspec_device_up and sunspec_uplink_records_total.
5. Update dashboards and alert rules to the new metric names.

Configuration

The collector reads its settings from built-in defaults, an optional config file (TOML or JSON) and SUNSPEC_* environment variables. Every setting has a default, so an empty configuration is valid: it scans 192.168.1.0/24 on port 502 and, with no Kafka brokers set, only logs records.

Two example files ship with the documentation:

• config.example.toml: a config file with every section.
• sunspec-collector.env: an environment file, used by the systemd unit as /etc/sunspec-collector.env.

Load order

Values are resolved in this order; a later source overrides an earlier one:

1. Built-in defaults
2. Config file (TOML or JSON)
3. Environment variables (SUNSPEC_*)

A typical deployment keeps a config file per site and overrides a few values per host or container with environment variables.

Choosing the config file

collector-app --config /etc/sunspec-collector.toml
collector-app --config=/etc/sunspec-collector.toml
SUNSPEC_CONFIG=/etc/sunspec-collector.toml collector-app

--config takes precedence over SUNSPEC_CONFIG. A file whose name ends in .json is parsed as JSON; any other file is parsed as TOML. With neither option set, no file is read and only the defaults and environment variables apply. A file that is named but cannot be read is an error.

Strict validation

Configuration errors stop the collector at startup with exit status 78 (EX_CONFIG). The systemd unit does not restart on that status (RestartPreventExitStatus=78), so a bad setting leaves the service failed, with the error in the journal, instead of restarting it every few seconds. Nothing falls back to a default silently. The following are errors:

• Unknown keys or sections in the config file, and values of the wrong type (for example a string where a number is expected, or unit_id = 300).
• A SUNSPEC_* variable whose value cannot be parsed. The error names the variable.
• An invalid static device entry (empty host, host containing whitespace, unit ID outside 0–255).
• kafka.compression or kafka.acks values outside the supported lists, and kafka.acks of 0 or 1 while kafka.enable_idempotence is true (the default).
• Out-of-range values: zero ports, intervals, timeouts and sizes where at least 1 is required, modbus.max_batch_size outside 1–125, an invalid CIDR subnet, an empty unit ID list, an invalid Kafka topic name, an empty broker list.
• Model settings (see Polling profiles): a model ID outside 1–65534, an empty include_models, a model in both include_models and exclude_models, a model_intervals_s entry of 0, and a static device listed twice.
• A framing other than tcp or rtu, and static devices behind the same RTU converter (same host and port, framing = "rtu") with different request_timeout_ms or max_batch_size: they share one connection.

A misspelled key in the file:

[poller]
poll_intervall_ms = 1000

Error: load config failed

Caused by:
    0: parse toml config /etc/sunspec-collector.toml
    1: TOML parse error at line 2, column 1
         |
       2 | poll_intervall_ms = 1000
         | ^^^^^^^^^^^^^^^^^
       unknown field `poll_intervall_ms`, expected one of `poll_interval_ms`, `request_timeout_ms`, `jitter_ms`, `stall_timeout_ms`, `include_models`, `exclude_models`, `model_intervals_s`

An unparsable environment variable:

$ SUNSPEC_POLL_INTERVAL_MS=1s collector-app
Error: load config failed

Caused by:
    SUNSPEC_POLL_INTERVAL_MS="1s" is invalid: invalid digit found in string

A value that parses but is not allowed:

$ SUNSPEC_KAFKA_COMPRESSION=brotli collector-app
Error: config validation failed

Caused by:
    kafka.compression must be one of none, gzip, snappy, lz4, zstd, got "brotli"

load config failed covers reading and parsing (file syntax, unknown keys, types, environment values, static devices). config validation failed covers range and value checks on the merged result.

Settings are also checked against each other. An idempotent producer needs acks=all, so this is rejected before the Kafka client is created:

$ SUNSPEC_KAFKA_ACKS=1 collector-app
Error: config validation failed

Caused by:
    kafka.acks must be all (or -1) while kafka.enable_idempotence is true

Two startup errors come after validation: kafka publisher init failed if librdkafka rejects a setting when the producer is created, and bind metrics port <port> if the HTTP port cannot be bound (see [metrics]).

Empty environment variables

A variable that is set to an empty string counts as set. SUNSPEC_POLL_INTERVAL_MS= is a parse error and SUNSPEC_KAFKA_BROKERS= fails validation. Comment out variables you do not want to set. The exceptions are lists: an empty SUNSPEC_STATIC_DEVICES is an empty list, which selects subnet mode; an empty SUNSPEC_INCLUDE_MODELS means every model; and an empty SUNSPEC_EXCLUDE_MODELS or SUNSPEC_MODEL_INTERVALS_S means none.

Deprecated keys

These keys are still accepted so that existing files and environments keep loading. They have no effect; the collector logs a warning at startup when one is set.

Reference

Durations are integers in the unit given by the key name (_ms, _s). "≥ 1" means 0 is rejected. A dash in the env var column means the setting can only be set in the config file.

[discovery]

The device set comes from either a static list or a subnet scan. When static_devices is non-empty, no scan runs and subnet, max_concurrency, per_host_timeout_ms, unit_ids and rescan_interval_s are not used (they are still validated).

[poller]

A sample that cannot be queued for ingest within one poll interval is dropped and counted in sunspec_samples_dropped_total{reason="channel_full"}, so a slow buffer never blocks polling.

A session also ends after 10 consecutive poll cycles in which at least one read failed. Ended sessions are retried with the backoff described under runtime.respawn_delay_ms.

[modbus]

With the defaults, one request to an unresponsive device takes up to three timeouts plus 300 ms of backoff before it fails. Keep poller.request_timeout_ms × (retry_count + 1) well below the poll interval if you want failed cycles to be detected quickly.

After a transport error or timeout the client drops the connection and reconnects on the next read. A Modbus exception keeps the connection.

[sunspec]

Models are rediscovered every time a device session starts, so a firmware change that alters the model chain is picked up after the next reconnect.

[buffer]

See Buffer Maintenance for how the buffer works and how to size it.

In Docker, the image runs in /app/data, the directory to mount a volume on. The image does not set SUNSPEC_BUFFER_PATH, so buffer.path from a config file applies. A relative buffer.path lands in /app/data; an absolute path outside /app/data is not in the volume and is lost when the container is removed.

[kafka]

The producer also sets linger.ms=50; this is not configurable.

Connection security (TLS and SASL)

Rules checked at startup:

• ssl_* settings need ssl or sasl_ssl; sasl_* settings need sasl_plaintext or sasl_ssl. Setting them with another protocol is an error, so a half-applied security configuration cannot silently fall back to plaintext.
• *_file settings read a file that contains only the secret (a trailing newline is removed). Setting both a secret and its _file form is an error, as is an empty file.
• Secrets never appear in logs: they are redacted in debug output.
• librdkafka loads the CA and client certificate when the producer is created, so an unreadable or invalid PEM file stops the collector at startup (kafka publisher init failed).

GSSAPI (Kerberos) and OAUTHBEARER are not supported. Certificates are read at startup; restart the collector after rotating them (the buffer keeps unsent data across the restart). See Securing the Kafka connection for deployment examples.

[metrics]

The Docker image's HEALTHCHECK calls http://localhost:${SUNSPEC_METRICS_PORT:-9090}/healthz, so it follows the port when you set it with SUNSPEC_METRICS_PORT. If you set metrics.port in a config file instead, or use 0, the health check still probes 9090 and fails; set the port with the environment variable in containers.

[runtime]

Environment-only settings

Static devices

A static device is a host and a Modbus unit ID. Each entry becomes one supervised poller, keyed host/unit (for example 192.168.1.20/1). That key is used in logs, in the device metric label and as the Kafka record key.

In a config file, use an array of tables (TOML) or an array of objects (JSON). unit_id is optional and defaults to 1:

[[discovery.static_devices]]
ip = "192.168.1.20"

[[discovery.static_devices]]
ip = "modbus-gw.example.net"
unit_id = 3

In the environment, use a comma-separated list of host[:unit]:

SUNSPEC_STATIC_DEVICES=192.168.1.20,192.168.1.21:1,modbus-gw.example.net:3

Rules for both forms:

• The host is an IPv4 address or a hostname. Hostnames are resolved on every connect, and each resolved address is tried in turn.
• The unit ID is 0–255 and defaults to 1.
• The host must not be empty or contain whitespace.
• In the environment form, spaces around entries and empty entries are ignored. The host and unit are split at the last :, so this form cannot express an IPv6 address literal.

Gateways expose several units on one host. List each unit as its own entry:

SUNSPEC_STATIC_DEVICES=192.168.1.100:1,192.168.1.100:2,192.168.1.100:3

discovery.unit_ids / SUNSPEC_DISCOVERY_UNIT_IDS apply only to hosts found by a subnet scan, not to static entries.

Each host and unit ID may be listed only once. Entries in a config file can also carry per-device settings.

Polling profiles

See Polling profiles, including per-device settings.

Logging

Logging is configured with environment variables only.

Logs go to standard output. ANSI colours are used only when standard output is a terminal.

Steady-state operation is quiet at info: per-cycle and per-batch messages are logged at debug. For a closer look at the collector itself, RUST_LOG=info,collector_app=debug,poller_actor=debug reads well. Useful debug targets:

• poller_actor: poll cycle timings, and each base address discovery tries without finding a SunSpec map.
• modbus_client: every read, and every failed attempt before a retry (the poller logs the read that finally failed at warn).
• collector_app::uplink: every uplink batch.
• avro_kafka: records handled by the log-only sink when no brokers are set, and every failed broker connection. At info a failed connection is logged at warn at most once per 5 minutes ("Kafka broker connection failed"), and the uplink logs "records delivered again" when an outage ends.
• librdkafka: the Kafka client library's own log lines.
• discovery: every probe during a subnet scan.

Command-line options

See Command-line options.

Complete examples

Both examples below pass strict validation.

TOML

# /etc/sunspec-collector.toml
# A non-empty static_devices list selects static mode, so the subnet scan
# settings below are validated but not used.

[discovery]
subnet = "192.168.1.0/24"
port = 502                        # also sets modbus.port
max_concurrency = 64
per_host_timeout_ms = 200
unit_ids = [1]
rescan_interval_s = 600

[[discovery.static_devices]]
ip = "192.168.1.20"               # unit_id defaults to 1

[[discovery.static_devices]]
ip = "modbus-gw.example.net"
unit_id = 2
poll_interval_ms = 2000           # per-device settings: see Polling profiles
max_batch_size = 60

[poller]
poll_interval_ms = 1000
request_timeout_ms = 1000
jitter_ms = 250
stall_timeout_ms = 30000
exclude_models = [123]

[poller.model_intervals_s]
1 = 3600
120 = 3600
121 = 600

[modbus]
max_batch_size = 125
retry_count = 2
retry_backoff_ms = 100
retry_max_backoff_ms = 2000
# inter_read_delay_ms = 5         # unset by default: no pause between split reads

[sunspec]
base_address = 40000

[buffer]
path = "/var/lib/sunspec-collector/buffer.sqlite"
batch_size = 100
drain_interval_ms = 500
max_rows = 1000000
max_age_s = 604800
shutdown_drain_timeout_ms = 5000

[kafka]
brokers = "kafka-1.example.net:9092,kafka-2.example.net:9092"
topic = "sunspec.telemetry"
client_id = "sunspec-collector"
acks = "all"
compression = "zstd"
timeout_ms = 5000
enable_idempotence = true

[metrics]
port = 9090

[runtime]
channel_capacity = 256
respawn_delay_ms = 1000

JSON

Subnet mode, scanning two unit IDs per host, with a slower poll interval and a larger uplink batch:

{
  "discovery": {
    "subnet": "10.20.0.0/24",
    "port": 502,
    "max_concurrency": 64,
    "per_host_timeout_ms": 200,
    "unit_ids": [1, 2],
    "rescan_interval_s": 600
  },
  "poller": {
    "poll_interval_ms": 5000,
    "request_timeout_ms": 1500,
    "jitter_ms": 1000,
    "model_intervals_s": { "1": 3600, "120": 3600, "121": 600 }
  },
  "modbus": {
    "max_batch_size": 100,
    "retry_count": 2,
    "retry_backoff_ms": 100,
    "retry_max_backoff_ms": 2000,
    "inter_read_delay_ms": 10
  },
  "sunspec": {
    "base_address": 40000
  },
  "buffer": {
    "path": "/var/lib/sunspec-collector/buffer.sqlite",
    "batch_size": 500,
    "drain_interval_ms": 500,
    "max_rows": 2000000,
    "max_age_s": 172800,
    "shutdown_drain_timeout_ms": 5000
  },
  "kafka": {
    "brokers": "kafka.example.net:9092",
    "topic": "site-a.sunspec.telemetry",
    "client_id": "sunspec-collector-site-a",
    "acks": "all",
    "compression": "zstd",
    "timeout_ms": 10000,
    "enable_idempotence": true
  },
  "metrics": {
    "port": 9090
  },
  "runtime": {
    "channel_capacity": 512,
    "respawn_delay_ms": 1000
  }
}

Save it with a .json extension so it is parsed as JSON.

Common setups

No Kafka (records are only logged)

SUNSPEC_STATIC_DEVICES=192.168.1.20:1 RUST_LOG=info,avro_kafka=debug collector-app

With the systemd unit, comment out the SUNSPEC_KAFKA_BROKERS line in /etc/sunspec-collector.env; an empty value fails validation.

Subnet scan with Kafka

SUNSPEC_SUBNET=10.0.0.0/24 \
SUNSPEC_KAFKA_BROKERS=kafka.internal:9092 \
SUNSPEC_KAFKA_TOPIC=solar.telemetry \
collector-app

Docker with a config file

Mount the file and point SUNSPEC_CONFIG at it (or pass --config /app/collector.toml after the image name, since the image's entrypoint is /app/collector-app):

docker run -d --name sunspec-collector \
  -p 9090:9090 \
  -v "$(pwd)/collector.toml:/app/collector.toml:ro" \
  -v sunspec-data:/app/data \
  -e SUNSPEC_CONFIG=/app/collector.toml \
  sunspec-collector

Simulator on a non-standard port

cargo run -p sunspec-sim -- --bind 127.0.0.1:1502 --units 1,2
SUNSPEC_STATIC_DEVICES=127.0.0.1:1,127.0.0.1:2 SUNSPEC_PORT=1502 cargo run -p collector-app

Command-line options

Other arguments are ignored.

Running the binary

collector-app [--config PATH] [--print-schema]

Other arguments are ignored. Without a config file the collector starts from the compiled defaults and SUNSPEC_* environment variables, which override file values when both are used:

SUNSPEC_STATIC_DEVICES=192.168.1.20:1,192.168.1.21:1 \
SUNSPEC_KAFKA_BROKERS=kafka.example.internal:9092 \
  ./collector-app

Without SUNSPEC_KAFKA_BROKERS (or kafka.brokers) nothing is sent to Kafka: records are only logged at debug level. Every setting is described in Configuration.

• Logging: RUST_LOG sets the filter (default info, for example info,poller_actor=debug); SUNSPEC_LOG_FORMAT=json writes one JSON object per line (text is the default; any other value fails at startup). Colours are used only when stdout is a terminal.
• Files: the buffer is sunspec-buffer.sqlite in the working directory by default, with SQLite's -wal and -shm files next to it. In the Docker image the working directory is /app/data, so the default is /app/data/sunspec-buffer.sqlite; the example systemd environment file sets /var/lib/sunspec-collector/buffer.sqlite.
• Ports: /metrics and /healthz on metrics.port (default 9090). If the port cannot be bound, the collector exits at startup with an error containing bind metrics port <port>.
• Signals: SIGINT and SIGTERM start a graceful shutdown.
• Exit status: 0 after a graceful shutdown. Startup errors are printed to stderr, and the status says whether trying again can help:
  • 78 (EX_CONFIG): a setting is wrong: configuration that does not load or validate, an invalid SUNSPEC_LOG_FORMAT, or Kafka settings the producer rejects (such as an unreadable CA file). The systemd unit does not restart on this status (RestartPreventExitStatus=78).
  • 1: anything else, such as a metrics port that cannot be bound or a buffer that cannot be opened. These can pass, so the unit restarts the service.

HTTP endpoints

All four endpoints are served on metrics.port (default 9090) on all IPv4 interfaces.

/metrics

Prometheus text format. Every metric has HELP text. Metrics ending in _seconds are histograms with buckets at 0.001, 0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5 and 10 seconds.

curl -s http://localhost:9090/metrics | grep '^sunspec_'

/healthz

Returns 200 while both the ingest task and the uplink have checked in within the last 120 s, and 503 otherwise. The body is the same JSON in both cases:

{"healthy":true,"ingest_age_s":0.7,"uplink_age_s":0.3,"devices_up":2,"devices_total":2}

Device outages do not make the collector unhealthy, because restarting the collector would not bring a device back. A Kafka outage does not either: the uplink keeps checking in while it backs off. Use the metrics and alerts below to detect both.

The Docker HEALTHCHECK calls this endpoint, and the systemd watchdog uses the same check.

If metrics.port cannot be bound (for example, it is already in use), the collector exits at startup with Error: bind metrics port <port> and the operating-system error.

/devices

The live view of every supervised device: its state, what its latest session discovered, and the latest decoded reading of each polled model. Use it when commissioning ("is it reading my inverter, and are the values right?") or to see data without a Kafka consumer.

curl -s localhost:9090/devices                     # every device
curl -s localhost:9090/devices/192.168.1.50/126    # one device (404 if it is not supervised)

{"devices": [{
  "device": "192.168.1.50/126", "host": "192.168.1.50", "unit_id": 126,
  "up": true, "last_success_ms": 1792250000123, "restarts": 0,
  "base_address": 40000, "models": [1, 103, 120, 160], "polled_models": [1, 103, 160],
  "readings": [
    {"model_id": 103, "model_name": "inverter_three_phase", "collected_at_ms": 1792250000123,
     "age_s": 0.4, "points": {"A": 7.98, "PhVphA": 230.3, "W": 5509.0, "Hz": 50.02, "St": 4}}
  ]
}]}

Only the latest reading of each model is kept, so memory does not grow. A device that has never answered is listed with empty models and readings.

The endpoint exposes device data (readings, models, addresses) to anyone who can reach metrics.port, like /metrics. Keep the port on a management network or behind a firewall.

/models

The bundled SunSpec model definitions, for describing what records and /devices contain:

curl -s localhost:9090/models          # {"models": [{"id": 1, "name": "common", "label": "Common"}, ...]}
curl -s localhost:9090/models/103      # one model: every point with type, units, label, description, symbols

Point names match records, with [*] for a repeating group's index (module[*].DCA). An unknown ID returns 404. collector-app --print-models prints the same metadata for every model, for consumers that load it once.

Metrics reference

Notes:

• The device label is host/unit, for example 192.168.1.20/1.
• sunspec_device_up is published with the value 0 as soon as a device's poller starts, so a device that has never answered has a series with the value 0. Most other series appear when they are first recorded; in particular sunspec_device_last_success_timestamp_seconds appears only after a device's first successful read.
• sunspec_poll_errors_total counts a failed connect at the start of a session, Modbus errors while discovering the model chain, and failed model reads while polling. Exceptions returned while probing the candidate base addresses are not counted, because the collector expects them and moves on to the next base. A device with no SunSpec map at any base therefore shows only sunspec_poller_restarts_total and a device session ended log line.
• kind values: exception (the device returned a Modbus exception), timeout (a read or a connect timed out), transport (I/O or protocol error on the connection, or the device closed it), connect (the connection was refused or failed, or the host could not be resolved), address (the read would run past register 65535).
• sunspec_uplink_errors_total counts per attempt: a record that fails three times counts three times. During a Kafka outage it grows by up to buffer.batch_size per attempt.
• Without kafka.brokers, records handed to the log-only sink count in sunspec_uplink_records_total.
• sunspec_uplink_publish_seconds is recorded only for batches in which at least one record was acknowledged.
• reason="write_error" counts samples lost because an SQLite write failed (for example, a full disk). reason="corrupt" counts rows that could not be decoded or encoded and were deleted.

Kafka record contract

Schema version 2. This format is not compatible with earlier versions of the collector (see Earlier format).

Record

• Topic: kafka.topic (default sunspec.telemetry).

• One record per sample, that is per model read from one device.

• Key: device_key, host/unit_id, for example 192.168.1.20/1. With librdkafka's default partitioner (CRC32 of the key) all records of a device go to the same partition.

• Value: Avro single-object encoding:

  C3 01 | 8-byte CRC-64-AVRO (Rabin) fingerprint of the schema, little-endian | Avro binary datum
  

• Headers:

  • content-type: application/avro; encoding=single-object
  • schema-fingerprint: <16 hex characters>: the 8 fingerprint bytes in the order they appear in the value.

Records are published in buffer order, but a record that failed delivery is retried in a later batch, after records that were acknowledged. Order consumers by collected_at_ms when order matters.

Schema

com.rusty.sunspec.v2.SunspecSample, in crates/avro-kafka/schemas/sunspec_sample.avsc; collector-app --print-schema prints it.

Point semantics, as described in SunSpec decoding:

• names are the SunSpec point names; repeating groups are group[i].Point (e.g. module[0].DCA) and fixed sub-groups group.Point;
• scaled values are double; enums, bitfields and unscaled integers are long; strings are string, trimmed;
• "not implemented" values, and points whose scale factor is not implemented, are null;
• the model header (ID, L), scale-factor points and padding are omitted;
• models without a bundled definition have an empty points map; only registers is set.

points and labels are Avro maps, so their order is not preserved. Point units, labels and descriptions are in the model catalog, by model ID and point name.

Schema evolution

Changes that old readers can resolve, such as a new field with a default, keep the com.rusty.sunspec.v2 namespace and get a minor schema version in the CHANGELOG (2.1 added labels). They still change the schema's fingerprint, so a consumer that resolves the writer schema by fingerprint needs the new schema (collector-app --print-schema) before it reads new records. A change that old readers cannot resolve would get a new namespace (v3) and a breaking CHANGELOG entry.

A model 103 record, shown as JSON for readability (unions unwrapped, lists shortened):

{
  "device_key": "192.168.1.20/1",
  "ip": "192.168.1.20",
  "unit_id": 1,
  "model_id": 103,
  "model_name": "inverter_three_phase",
  "start": 40070,
  "collected_at_ms": 1760000000123,
  "points": { "A": 12.34, "PhVphA": 230.1, "W": 4321.0, "Hz": 50.0, "St": 4, "VA": null, ... },
  "labels": { "St": "MPPT", "Evt1": "", ... },
  "registers": [103, 50, 1234, ...]
}

Reading records

• Rust: avro_kafka::decode(bytes) checks the header and fingerprint and returns a Sample (points sorted by name).
• Other languages: check that the value starts with C3 01 and that the next 8 bytes match the fingerprint of the schema you hold, then decode the rest as an Avro binary datum with that schema. Most Avro libraries implement single-object decoding directly (for example BinaryMessageDecoder in Java).

Producer settings

acks=all, enable.idempotence=true, compression.type=zstd, linger.ms=50 (fixed) and message.timeout.ms=5000 by default. Every setting except linger.ms can be changed in the [kafka] section. An idempotent producer requires acks=all, so configuration validation rejects kafka.acks 0 or 1 while kafka.enable_idempotence is true (the default).

Connection security is librdkafka's: security.protocol (plaintext, ssl, sasl_plaintext, sasl_ssl), the ssl.* CA, client certificate and key for (mutual) TLS, and SASL PLAIN or SCRAM-SHA-256/512 credentials. Passwords are held in a Secret type whose debug output is redacted and can be read from files at startup. Validation rejects settings that do not match the protocol, so a half-configured TLS or SASL setup fails instead of falling back to plaintext.

Earlier format

Earlier versions sent one Avro Object Container File per Kafka message, mixing samples from several devices, with the schema embedded in every message, no key, raw registers only, and model names such as three_phase_inverter. Consumers of that format must be updated.

Supported SunSpec models

The collector bundles 112 official SunSpec model definitions (3217 points) and decodes every one of them. Each page below lists a group of models with their points: the name records use, the type, units, label and description from the definitions, and the names of enum values and bitfield bits. In a point name, [*] stands for a repeating group's index (module[*].DCA covers module[0].DCA, module[1].DCA and so on).

The same data is available from a running collector at /models and from collector-app --print-models.

Common and network

Inverters and inverter controls

Meters

Environmental sensors

String combiners

Solar modules

Trackers

DER (IEEE 1547-2018)

Storage

Test and vendor models

Common and network

Point names are the ones records use; [*] stands for a repeating group's index. See Supported SunSpec models for every group.

Model 1: Common

Name in records: common.

All SunSpec compliant devices must include this as the first model

Model 2: Basic Aggregator

Name in records: aggregator.

Aggregates a collection of models for a given model id

Value names:

• St (enum16): 1 OFF, 2 ON, 3 FULL, 4 FAULT
• Evt (bitfield32): bit 0 GROUND_FAULT, bit 1 INPUT_OVER_VOLTAGE, bit 2 RESERVED_2, bit 3 DC_DISCONNECT, bit 4 RESERVED_4, bit 5 RESERVED_5, bit 6 MANUAL_SHUTDOWN, bit 7 OVER_TEMPERATURE, bit 8 RESERVED_8, bit 9 RESERVED_9, bit 10 RESERVED_10, bit 11 RESERVED_11, bit 12 BLOWN_FUSE, bit 13 UNDER_TEMPERATURE, bit 14 MEMORY_LOSS, bit 15 ARC_DETECTION, bit 16 THEFT_DETECTION, bit 17 OUTPUT_OVER_CURRENT, bit 18 OUTPUT_OVER_VOLTAGE, bit 19 OUTPUT_UNDER_VOLTAGE, bit 20 TEST_FAILED
• Ctl (enum16): 0 NONE, 1 AUTOMATIC, 2 FORCE_OFF, 3 TEST, 4 THROTTLE

Model 3: Secure Dataset Read Request

Name in records: model_3.

Request a digital signature over a specified set of data registers

Value names:

• Alg (enum16): 0 NONE, 1 AES-GMAC-64, 2 ECC-256

Model 4: Secure Dataset Read Response

Name in records: model_4.

Compute a digital signature over a specified set of data registers

Value names:

• Sts (enum16): 0 SUCCESS, 1 DS, 2 ACL, 3 OFF
• Alm (enum16): 0 NONE, 1 ALM
• Alg (enum16): 0 NONE, 1 AES-GMAC-64, 2 ECC-256

Model 5: Secure Write Request

Name in records: model_5.

Include a digital signature along with the control data

Value names:

• Alg (enum16): 0 NONE, 1 AES-GMAC-64, 2 ECC-256

Model 6: Secure Write Sequential Request

Name in records: model_6.

Include a digital signature along with the control data

Value names:

• Alg (enum16): 0 NONE, 1 AES-GMAC-64, 2 ECC-256

Model 7: Secure Write Response Model (DRAFT 1)

Name in records: model_7.

Include a digital signature over the response

Value names:

• Sts (enum16): 0 SUCCESS, 1 DS, 2 ACL, 3 OFF, 4 VAL
• Alm (enum16): 0 NONE, 1 ALM
• Alg (enum16): 0 NONE, 1 AES-GMAC-64, 2 ECC-256

Model 8: Get Device Security Certificate

Name in records: model_8.

Security model for PKI

Value names:

• Fmt (enum16): 0 NONE, 1 X509_PEM, 2 X509_DER

Model 9: Set Operator Security Certificate

Name in records: model_9.

Security model for PKI

Value names:

• Fmt (enum16): 0 NONE, 1 X509_PEM, 2 X509_DER
• Typ (enum16): 0 DEV_KEY_PAIR, 1 DEV_SHARED_KEY, 2 OPERATOR_PUB, 3 OPERATOR_SHARED, 4 CA_PUB
• Alg (enum16): 0 NONE, 1 AES-GMAC-64, 2 ECC-256

Model 10: Communication Interface Header

Name in records: model_10.

To be included first for a complete interface description

Value names:

• St (enum16): 0 DOWN, 1 UP, 2 FAULT
• Typ (enum16): 0 UNKNOWN, 1 INTERNAL, 2 TWISTED_PAIR, 3 FIBER, 4 WIRELESS

Model 11: Ethernet Link Layer

Name in records: model_11.

Include to support a wired ethernet port

Value names:

• CfgSt (bitfield16): bit 0 LINK, bit 1 FULL_DUPLEX, bit 2 AUTO_NEG1, bit 3 AUTO_NEG2, bit 4 AUTO_NEG3, bit 5 RESET_REQUIRED, bit 6 HW_FAULT
• St (enum16): 0 UNKNOWN, 1 ENABLED, 2 DISABLED, 3 TESTING
• Ctl (bitfield16): bit 0 AUTO, bit 1 FULL_DUPLEX

Model 12: IPv4

Name in records: model_12.

Include to support an IPv4 protocol stack on this interface

Value names:

• CfgSt (enum16): 0 NOT_CONFIGURED, 1 VALID_SETTING, 2 VALID_HW
• ChgSt (bitfield16): bit 0 PENDING
• Cap (bitfield16): bit 0 DHCP, bit 1 BOOTP, bit 2 ZEROCONF, bit 3 DNS, bit 4 CFG_SETTABLE, bit 5 HW_CONFIG, bit 6 NTP_CLIENT, bit 7 RESET_REQUIRED
• Cfg (enum16): 0 STATIC, 1 DHCP, 2 BOOTP, 3 ZEROCONF
• Ctl (enum16): 0 ENABLE_DNS, 1 ENABLE_NTP

Model 13: IPv6

Name in records: model_13.

Include to support an IPv6 protocol stack on this interface

Value names:

• CfgSt (enum16): 0 NOT_CONFIGURED, 1 VALID_SETTING, 2 VALID_HW
• ChgSt (bitfield16): bit 0 PENDING
• Cap (bitfield16): bit 0 DHCP, bit 1 BOOTP, bit 2 ZEROCONF, bit 3 DNS, bit 4 CFG_SETTABLE, bit 5 HW_CONFIG, bit 6 NTP_CLIENT, bit 7 RESET_REQUIRED
• Cfg (enum16): 0 STATIC, 1 DHCP, 2 BOOTP, 3 ZEROCONF
• Ctl (enum16): 0 ENABLE_DNS, 1 ENABLE_NTP

Model 14: Proxy Server

Name in records: model_14.

Include this block to allow for a proxy server

Value names:

• Cap (bitfield16): bit 0 NO_PROXY, bit 1 IPV4_PROXY, bit 2 IPV6_PROXY

Model 15: Interface Counters Model

Name in records: model_15.

Interface counters

Model 16: Simple IP Network

Name in records: model_16.

Include this model for a simple IPv4 network stack

Value names:

• Cfg (enum16): 0 STATIC, 1 DHCP
• Ctl (bitfield16): bit 0 ENABLE_DNS, bit 1 ENABLE_NTP
• LnkCtl (bitfield16): bit 0 AUTONEGOTIATE, bit 1 FULL_DUPLEX, bit 2 FORCE_10MB, bit 3 FORCE_100MB, bit 4 FORCE_1GB