IoT Gateway

Repository: RoamView-Technologies/roamview-iot-gateway

The IoT Gateway is the cloud end of the robot link. Robots connect to it over Wi-Fi to receive live control commands and scheduled-inspection notices and to send telemetry and video. It relays video to the Streaming Service and receives control commands on the path App → API Gateway → Streaming Service → IoT Gateway (SP-4.1.1). It runs on the always-on App server next to the API Gateway, Streaming Service and Ingestion Service (see the Deployment Diagram on the Software Architecture wiki page).

Related use cases: UC-GU01 Live Walkthrough, UC-OA01 Schedule Inspections, UC-GU07 Send Video Stream. Related specs: SP-4.1.1 (command latency), SP-4.1.6 (video relay capacity) in the Software Requirement Specification.

flowchart TB
    subgraph IOT["«module» roamview-iot-gateway"]
        direction TB
        MAIN["«package» cmd/iot-gateway<br/>main: load config, create registry,<br/>start server, graceful shutdown on SIGTERM"]

        subgraph INT["«package» internal"]
            direction TB
            SRV["«package» server<br/>NewRouter() · New()<br/>route table, http.Server timeouts"]
            HND["«package» handlers<br/>Health · Ready · Version · Robots<br/>NotImplemented · WriteJSON"]
            ROB["«package» robot<br/>Registry: Connect · Touch ·<br/>Disconnect · Get · List"]
            MW["«package» middleware<br/>RequestID · Logging · Recover · Chain"]
            CFG["«package» config<br/>Load() from env vars"]
            VER["«package» version<br/>Version · Commit (ldflags)"]
        end
    end

    STD["«library» Go standard library<br/>net/http · log/slog · sync"]

    MAIN -->|«import»| CFG
    MAIN -->|«import»| SRV
    MAIN -->|«import»| ROB
    MAIN -->|«import»| VER
    SRV -->|«import»| CFG
    SRV -->|«import»| HND
    SRV -->|«import»| MW
    SRV -->|«import»| ROB
    HND -->|«import»| ROB
    HND -->|«import»| VER
    INT -.->|«use»| STD
    MAIN -.->|«use»| STD

Loading

Packages

Package	Responsibility	Depends on
cmd/iot-gateway	Entry point. Loads config, creates the robot registry, builds the server, handles SIGINT/SIGTERM and shuts down gracefully	config, server, robot, version
internal/server	Owns the route table and wraps it in middleware. Sets HTTP server timeouts (no write timeout, because robot links and video are long-lived)	config, handlers, middleware, robot
internal/handlers	Endpoints the gateway answers itself: /healthz, /readyz, /version, the robot status endpoints, and 501 placeholders for routes still to be built	robot, version
internal/robot	Thread-safe, in-memory registry of connected robots (robot ID, connected time, last-seen time). Does not depend on the robot transport	—
internal/middleware	Cross-cutting concerns applied to every request: request ID (X-Request-ID), structured logging, panic recovery	—
internal/config	Reads PORT (default 8081), APP_ENV, SHUTDOWN_TIMEOUT and STREAMING_SERVICE_URL from the environment	—
internal/version	Build version and commit, injected at link time	—

Dependencies only point downward: cmd → server → handlers → leaf packages. Leaf packages (robot, middleware, config, version) import nothing from this module, so each can be tested on its own. Everything under internal/ cannot be imported by other modules.

Interfaces

Exposes

Route	Caller	Status
GET /healthz, GET /readyz, GET /version	Orchestrator / ops	Implemented
GET /robots	API Gateway (/api/v1/iot/*)	Implemented: lists connected robots
GET /robots/{robotID}	API Gateway	Implemented: 404 if the robot is not connected
GET /robot/v1/connect	Robot	501: protocol not decided yet (WSS or MQTT-TLS)
POST /robots/{robotID}/commands	Streaming Service	501: live control (UC-GU01, SP-4.1.1)
POST /robots/{robotID}/inspections	API Gateway	501: notify the robot of a scheduled inspection (UC-OA01)
GET /robots/{robotID}/telemetry	API Gateway	501: robot telemetry

Calls

Target	Why	Status
Robot (Raspberry Pi 5)	Control commands and inspection notices over the robot link (WSS or MQTT-TLS, see the Deployment Diagram)	Planned
Streaming Service	Pass-through video relay (SP-4.1.6), set by STREAMING_SERVICE_URL	Planned (Task 9.4)

The API Gateway reaches this service through its /api/v1/iot/* proxy. An incoming X-Request-ID header is kept, so a request can be traced across services.

Planned packages (later tasks)

Package	Purpose	Related use cases / specs
internal/link	Robot transport: accepts the robot connection (WSS or MQTT-TLS, to be decided), authenticates the robot and updates the registry	UC-GU01, UC-OA01
internal/commands	Delivers control commands to the robot on a priority channel, separate from video	UC-GU01, SP-4.1.1
internal/telemetry	Receives robot status (battery, position) and exposes it to the API Gateway	UC-GU01
internal/video	Pass-through video relay to the Streaming Service, no decode or transcode, ≤ 2 frames buffered	UC-GU07, SP-4.1.6

Running it

See the repo README for run steps, configuration and CI.