thingsboard/thingsboard-gateway

ThingsBoard IoT Gateway

The ThingsBoard IoT Gateway is an open-source, Python-based application that enables seamless integration of legacy and third-party devices with the ThingsBoard IoT platform. It serves as a protocol adapter that collects data from external sources and publishes it to ThingsBoard via a unified format.

📖 What is ThingsBoard IoT Gateway?

💡 New to ThingsBoard? Learn what ThingsBoard is

---

🚀 Getting Started

Curious how the ThingsBoard IoT Gateway works in action?

➡️ Follow our Getting Started Guide to:

• 🚀 Run the gateway in minutes using pre-configured demo servers
• 🔄 Simulate device data collection and processing workflows
• 🧪 Explore telemetry, attributes, and RPCs without real devices
• 🖥️ Test integration with ThingsBoard Community or Professional Edition

💡 Ideal for evaluation, proof-of-concept, and learning how the gateway processes and routes data.

---

🔌 Gateway Features

ThingsBoard IoT Gateway supports a wide range of industrial and IoT protocols out of the box. Each connector enables collecting data from external systems, transforming it into a unified format, and forwarding it to ThingsBoard.

📟 Industrial & SCADA Protocols

• Modbus – Integrate with Modbus TCP/RTU devices like PLCs and energy meters.
• OPC-UA – Connect to industrial automation systems using the OPC-UA protocol.
• CAN – Communicate with devices over the Controller Area Network (e.g., automotive, industrial equipment).
• ODBC – Retrieve telemetry from SQL-compliant databases.

🌐 IoT & Networking Protocols

• MQTT – Subscribe to external MQTT brokers and ingest messages.
• REST API – Push data to REST endpoints created by gateway.
• Request Connector – Periodically pull data from HTTP(S) APIs and ingest response payloads.
• FTP – Read files from FTP/SFTP servers for batch data ingestion.
• Socket – Request data via raw TCP/UDP socket connections.
• SNMP – Poll SNMP devices to collect MIB data from routers, switches, sensors.
• XMPP – Receive telemetry from XMPP-based chat/device networks.

📡 Smart Energy & Charging

• OCPP – Integrate EV charging stations using Open Charge Point Protocol.

🏠 Smart Building & Home Automation

• BACnet – Gather building automation data (HVAC, lighting, fire systems).
• KNX – Interface with KNX-based building automation systems.
• BLE – Scan and connect to BLE-enabled devices (e.g., beacons, wearables).

🧩 Extensibility

• Custom Connectors – Build your own protocol handlers using Python to support any proprietary system or emerging protocol.

✨ All connectors support flexible configuration, data transformation, and integration with the ThingsBoard platform's device model.

🧰 Core Gateway Capabilities

In addition to multi-protocol support, the ThingsBoard IoT Gateway includes robust features for reliability, remote management, and automation:

🔒 Reliability & Resilience

• Data persistence – Buffers telemetry locally to prevent data loss during network or system outages.
• Automatic reconnection – Automatically restores connection to the ThingsBoard cluster after temporary failures.

🔄 Unified Data Processing

• Data mapping engine – Transforms raw input from devices into ThingsBoard’s unified data format using customizable converters.

🛠️ Remote Management & Control

• Remote configuration – Update and manage gateway configuration directly from the ThingsBoard web UI.
• Remote logging – View and stream logs remotely for troubleshooting and monitoring.
• Gateway service RPC methods – Interact with the gateway using platform-initiated RPC commands.
• Remote shell access – Run shell commands on the gateway host via the ThingsBoard platform.

🔄 Device Lifecycle Handling

• Device rename/removal detection – Automatically synchronizes device renames and deletions to keep the platform device list up to date.

🏗️ Architecture Overview

The IoT Gateway is implemented in Python, allowing powerful extension and customization. It follows a modular architecture resembling microservices.

• Custom connectors let you interface with new devices or services.
• Custom converters allow transformation of incoming messages to a ThingsBoard-compatible format.
• The Gateway provides simple integration APIs, and encapsulates common ThingsBoard related tasks: device provisioning, local data persistence and delivery, message converters and other.

Ideal for edge use cases where flexibility and protocol diversity are key.

---

💬 Support & Community

Need help or want to share ideas?

• 
• 💬 GitHub Discussions – Ask questions, propose features, or share use cases.
• ❓ StackOverflow – Use the thingsboard-gateway tag.

🐞 Found a bug? Please open an issue.

---

⭐ Contributing

We welcome contributions! Feel free to fork the repo, open PRs, or help triage issues.

---

⚖️ License

This project is licensed under the Apache 2.0 License.

---

🌟 Don't forget to star the repository to show your ❤️ and support!