Protocol Layer Overview

Customer Builds and JSON-Driven Selection

Like file system, logger, and time service, the protocol plane uses per-customer JSON + generated headers. The difference from a naive “pick A or B” model: protocol_config.json can enable several protocol entries at once (use: true on RigelMq, Orion TLV, ZD, Metallix…). Each brings its own protocolFunc hooks and connection defaults; the script composes INIT_PROTOCOLS so init/start run in order. Multiple sensors are not an afterthought—each active protocol names a linkedSensorName; the union drives INIT_SENSORS. One customer folder, one generator run, one firmware personality—spelled out in JSON.

Customer protocol_config.json and generate_protocol_config.py

Under Customers/<CustomerName>/Protocol/, each customer keeps a single protocol_config.json that declares which protocol blocks are on (one or many), their connection defaults (MQTT or TCP), and the sensors referenced by linkedSensorName. The Python tool Customers/generate_protocol_config.py reads that JSON and emits C headers so the gateway gets composed INIT_PROTOCOLS / INIT_SENSORS macros—no manual stitching.

End-to-end flow

flowchart LR
  subgraph IN["Input"]
    J[protocol_config.json]
  end
  subgraph PY["Python"]
    G[generate_protocol_config.py --customer NAME]
  end
  subgraph OUT["Generated C headers"]
    CUS[Customers/NAME/Protocol/cus_protocol_config.h]
    SHIM[Customers/Protocol_Config.h]
  end
  subgraph FW["Firmware"]
    APP[AppZMeterGw.c includes Protocol_Config.h]
    INIT[INIT_PROTOCOLS / INIT_SENSORS macros]
  end
  J --> G
  G --> CUS
  G --> SHIM
  SHIM -->|shim includes| CUS
  CUS --> APP
  APP --> INIT

Selection logic (active protocol and sensors)

flowchart TB
  P["protocol.use"]
  P --> AP["activeProtocol doc label"]
  P --> PL["protocols map use true or false each"]
  PL --> EMIT["emit INIT_PROTOCOLS for each use-true"]
  EMIT --> LINK["linkedSensorName per protocol"]
  LINK --> SENS["sensor union from linked names"]
  SENS --> MAC["SENSOR init macros plus INIT_SENSORS"]

Run from the repository root (paths below are relative to Aviora root):

PS Aviora> python Customers/generate_protocol_config.py --customer ZD_0101
Wrote C:\...\Customers\ZD_0101\Protocol\cus_protocol_config.h
Wrote C:\...\Customers\Protocol_Config.h

The shim Customers/Protocol_Config.h only includes the selected customer file, for example:

#include "ZD_0101/Protocol/cus_protocol_config.h"

Root fields (protocol_config.json)

protocol object

Per-protocol entry (example keys)

connection (MQTT vs TCP)

The script flattens connection into settings for emit_*_defaults:

sensors[] (ZD_0101 example)

Generated output (excerpt)

For ZD_0101 with only protocolRigelMq.use: true and linkedSensorName: electricityMeter, the customer header defines protocol macros, Rigel default IPs/ports/topics, INIT_PROTOCOLS, and INIT_SENSORS:

#define ACTIVE_PROTOCOL_NUMBER (1)
#include "Application/.../AppProtocolRigelMq.h"
#define APP_RIGEL_MQ_PROTOCOL_INIT_FUNC(serialNumber)   appProtocolRigelMqInit(serialNumber)
#define RG_RIGEL_DEFAULT_MQTT_BROKER_IP       "127.0.0.1"
/* ... */
#define INIT_PROTOCOLS(setErrorFlag)   do{ ... } while(0)
#define ACTIVE_SENDOR_NUMBER (1)
#define SENSOR_ELECTRICITYMETER_INITIALIZE_FUNC(setErrorFlag)   do{ ... } while(0)
#define INIT_SENSORS(setErrorFlag)   do{ ... } while(0)

Isolated Protocol Services

Each stack (ZD, Metallix, Orion, RigelMq) remains a self-contained module: framing, sessions, transport callbacks. When several are enabled, they still talk to the rest of the gateway through the same narrow seams—especially AppMeterOperations for meters and jobs. The UI or unrelated drivers do not care how many wire formats are live—only that requests resolve consistently.

What You Configure

protocol_config.json is the inventory: which protocols are on, broker/server endpoints, topics, device/pull addresses, and which sensor drivers back each link. Regenerate after edits so cus_protocol_config.h stays the single source of truth for that customer’s INIT_* story.

Implementations at a Glance

Architecture — multi-protocol, one meter core

A build can load several protocol modules when JSON says so; each uses its transport (TCP and/or MQTT). All operational traffic still meets at AppMeterOperations for metering, directives, and jobs—parallel front doors, one house.

flowchart LR
  subgraph CFG["protocol_config.json"]
    ON[Multiple use:true protocols possible]
  end
  subgraph ST["Protocol stacks"]
    P1[Stack A e.g. RigelMq]
    P2[Stack B e.g. Orion TLV]
  end
  MO[AppMeterOperations]
  NET[Head-ends / brokers]
  ON -.-> ST
  P1 --> MO
  P2 --> MO
  P1 --> NET
  P2 --> NET

Repository Layout

Application/AppZMeterGw/Services/Protocol/
├── inc/
│   ├── AppTcpConnManager.h
│   ├── AppMeterOperations.h
│   ├── AppProtocolZD.h
│   ├── AppProtocolMetallixTLV.h
│   ├── AppProtocolOrionTLV.h
│   └── AppProtocolRigelMq.h
├── src/
│   ├── AppTcpConnManager.c
│   ├── AppMeterOperations.c
│   ├── AppProtocolZD.c
│   ├── AppProtocolMetallixTLV.c
│   ├── AppProtocolOrionTLV.c
│   └── AppProtocolRigelMq.c
└── Test_Server/
    ├── ProtocolZD_TestServer.py
    ├── ProtocolMetallixTLV_TestServer.py
    ├── ProtocolOrionTLV_TestServer.py
    └── ProtocolRigelMq_TestServer.py

Push vs Pull (TCP-based Stacks)

Details: TCP Connection Service — non-blocking select, push and pull sockets, request-based connect/disconnect.

MQTT (broker-based stacks)

TCP push and pull are not the only transports. When protocol_config.json sets a protocol block’s connection to MQTT, that stack uses AppMqttConnService: one session to the configured broker, subscribe/publish on the topics you declare (including optional request/response pairs), with reconnect and link callbacks wired the same way across builds. The same binary can run MQTT and TCP protocols together—each enabled block picks its own transport from JSON; nothing extra is hand-coded in the app to mix them.

Details: MQTT Connection Service — broker attach, IncomingCb / LinkCb, reconnect. Protocol specifics: ProtocolRigelMq.

Documentation Map