Architecture

• Overview
• Main Components
  • Connector
    • Available Connectors
  • Converter
  • Event Storage
  • IndustryOS Client
  • Gateway Service
• Data Flow
  • Uplink Data Flow (Device to IndustryOS)
  • Downlink Data Flow (IndustryOS to Device)
• Configuration Management
  • Local Configuration
  • Remote Configuration
• Security
  • Connection Security
  • Connector Security
• Scalability
  • Horizontal Scaling
  • Vertical Scaling
  • Performance Tuning
• High Availability
  • Fault Tolerance
  • Monitoring
• Next Steps

The IndustryOS IoT Gateway is a software component designed to run on Linux-based microcomputers that support Python 3.7+. This page describes the main architectural components and their interactions.

Overview

The gateway acts as a bridge between legacy devices, third-party systems, and the IndustryOS platform. It handles protocol translation, data buffering, and ensures reliable delivery of device data to IndustryOS.

Main Components

Connector

The purpose of this component is to connect to external systems (e.g. MQTT broker or OPC-UA server) or directly to devices (e.g. Modbus, BLE or CAN). Once connected, the connector either polls data from those systems or subscribes to updates.

Poll vs Subscribe:

• Subscribe model is used for protocols that support publish/subscribe patterns (e.g. MQTT)
• Polling model is used for protocols that require regular data requests (e.g. Modbus, CAN)

The connector is also able to push updates to devices either directly or via external systems.

Available Connectors

Industrial Protocols:

• Modbus
• OPC-UA
• BACnet
• SNMP
• KNX
• OCPP

IoT Protocols:

• MQTT

Network Protocols:

• Socket (TCP/UDP)
• CAN

Data Sources:

• ODBC
• REST
• FTP
• Request (HTTP/HTTPS)

Communication:

• BLE (Bluetooth Low Energy)
• XMPP

Custom: It is possible to define your own connector using the customisation guide.

Converter

Converters are responsible for converting data from protocol-specific format to/from IndustryOS format. Converters are invoked by Connectors and are often specific to the protocol supported by the Connector.

Converter Types:

1. Uplink Converter: Converts data from specific protocol to IndustryOS format
2. Downlink Converter: Converts messages from IndustryOS to specific protocol format

Converters handle:

• Device name extraction
• Device profile mapping
• Attribute parsing
• Telemetry data extraction
• Timestamp handling

It is possible to define your own converter using the customisation guide.

Event Storage

The Event Storage is used to temporarily store telemetry and other events produced by Connectors until they are delivered to IndustryOS.

Storage Implementations:

1. In-Memory Queue
   • Minimises IO operations
   • Faster performance
   • May lose messages in case of gateway process restart
   • Recommended for: Stable environments with reliable power
2. Persistent File Storage
   • Survives process restarts
   • Executes IO operations to the file system
   • Guarantees data delivery
   • Recommended for: Critical data that must not be lost

Both implementations ensure that device data is eventually delivered in case of network outages.

IndustryOS Client

The Gateway communicates to IndustryOS via MQTT protocol using the Gateway MQTT API. The IndustryOS Client is a separate thread that polls Event Storage and delivers messages once connection to IndustryOS is active.

Key Features:

• Connection monitoring
• Automatic reconnection
• Message batching for performance improvement
• Quality of Service (QoS) handling
• Session management
• Device state synchronisation

Communication Flow:

1. Client polls Event Storage for pending messages
2. Batches messages for efficient transmission
3. Publishes messages to IndustryOS via MQTT
4. Monitors acknowledgements and retries if necessary
5. Updates device connection status

Gateway Service

The Gateway Service is responsible for bootstrapping and orchestrating all other components.

Responsibilities:

• Starting and stopping Connectors
• Initialising Event Storage
• Managing IndustryOS Client lifecycle
• Collecting and reporting gateway statistics
• Persisting connected devices list
• Handling configuration updates
• Managing device subscriptions

Statistics Reporting: The service periodically reports to IndustryOS:

• Number of connected devices
• Number of incoming messages
• Connector status
• Gateway health metrics
• Error rates

Device Management: Gateway Service persists the list of connected devices to be able to re-subscribe to device configuration updates in case of gateway restart.

Data Flow

Uplink Data Flow (Device to IndustryOS)

1. Device sends data via protocol-specific interface
2. Connector receives data and passes to Converter
3. Converter transforms data to IndustryOS format
4. Event Storage temporarily stores the transformed data
5. IndustryOS Client retrieves data from Event Storage
6. IndustryOS Client publishes data to IndustryOS platform via MQTT
7. IndustryOS processes and stores device data

Downlink Data Flow (IndustryOS to Device)

1. IndustryOS sends command/configuration via MQTT
2. IndustryOS Client receives the message
3. Gateway Service routes message to appropriate Connector
4. Converter transforms message to protocol-specific format
5. Connector delivers message to device
6. Device processes the command and optionally sends response

Configuration Management

The gateway supports two configuration approaches:

Local Configuration

• Configuration files stored on gateway device
• Manual editing of JSON configuration files
• Suitable for: Development, testing, offline deployments

Remote Configuration

• Configuration managed through IndustryOS platform
• Real-time updates pushed to gateway
• Centralised management of multiple gateways
• Suitable for: Production deployments, distributed systems

Security

Connection Security

• TLS/SSL encryption for IndustryOS connection
• Certificate-based authentication
• Username/password authentication
• Anonymous connections (for testing only)

Connector Security

Each connector supports protocol-specific security:

• Username/password authentication
• Certificate-based authentication
• API keys
• Token-based authentication

Scalability

Horizontal Scaling

• Multiple gateway instances can be deployed
• Each gateway manages a subset of devices
• Load distribution across gateways

Vertical Scaling

• Worker threads for parallel message processing
• Configurable queue sizes
• Adjustable batch sizes for optimal performance

Performance Tuning

• Configurable report strategies
• Message batching
• Connection pooling
• Buffer size optimisation

High Availability

Fault Tolerance

• Automatic reconnection to IndustryOS
• Message buffering during network outages
• Graceful degradation
• Error recovery mechanisms

Monitoring

• Gateway status reporting
• Connector health checks
• Error logging and alerting
• Performance metrics

Next Steps

• Quick Start Guide - Get started with your first gateway
• Connectors - Learn about available connectors
• Custom Connectors - Build your own connector
• Gateway Features - Explore advanced features