DEV Community

Fastbee
Fastbee

Posted on

ESP32/ESP8266 MQTT Tutorial: Docker Deployment and Remote Device Control

#iot #esp32 #mqtt #opensource

A reproducible IoT development walkthrough: run FastBee Open Source Edition with Docker, configure an MQTT product and Thing Model, then publish telemetry and receive remote commands on an ESP32 or ESP8266.

Short answer: Deploy FastBee Open Source Edition, create and publish an MQTT product with the properties your device will report, then connect the board using its product ID, device number, user ID, and MQTT credentials. Use FastBee-Arduino’s documented firmware path for supported ESP32 boards; an ESP8266 needs a custom MQTT client that follows FastBee’s documented topics and payload format.

For: Developers who know basic networking and Arduino development and are setting up an IoT platform for the first time.
Outcome: Move from Wi-Fi connectivity to a complete loop: the platform sees device data, sends a command, and receives the device’s reported state.
Board support: Official FastBee-Arduino zero-code firmware targets the ESP32 family. An ESP8266 can follow the MQTT protocol below with firmware you write and maintain; do not flash the ESP32 firmware onto an ESP8266.

What you will build

  • A FastBee Open Source Edition test environment deployed with Docker Compose.
  • An MQTT product with a temperature property and a writable switch property.
  • An ESP32 or ESP8266 device that comes online, reports properties, and completes a remote-control round trip. 
Sensor/relay ↔ ESP32 or ESP8266 ↔ MQTT broker ↔ FastBee platform ↔ Web console
Enter fullscreen mode Exit fullscreen mode

1. Prerequisites

  • A server or local VM. FastBee’s current Docker guide lists a minimum of 2 CPU cores and 4 GB RAM; this is a documented deployment minimum, not production capacity planning.
  • Docker 20.10+ and Docker Compose 2.0+.
  • An ESP32 development board. An ESP8266 is also suitable for the custom MQTT firmware path.
  • A data-capable USB cable and Wi-Fi. Optional: a temperature sensor, low-voltage LED, or isolated relay module.
  • A browser and, optionally, MQTTX to validate the broker and topics before debugging firmware.

The host, board, and browser must be able to reach one another. In this guide, SERVER_IP is the FastBee host address. Replace PRODUCT_ID, DEVICE_NUM, and other placeholders with values from your own console. On the device, use a reachable server IP or hostname: localhost refers to the device itself.

2. Deploy FastBee with Docker

FastBee Open Source Edition includes a built-in MQTT Broker, so a first test does not require a separate EMQX deployment. FastBee’s current Docker guide lists Docker 20.10+, Docker Compose 2.0+, and a minimum of 2 CPU cores and 4 GB RAM. Treat those values as the documented deployment minimum; production sizing depends on workload and should be measured for the target deployment.

Run the official installer on a Linux host and select the open-source edition when prompted:

sudo wget -c https://hub.fastbee.cn/resource/install.sh && bash ./install.sh
Enter fullscreen mode Exit fullscreen mode

Check that the containers are running:

docker ps
Enter fullscreen mode Exit fullscreen mode

Open http://SERVER_IP:80 in a browser. The documented initial credentials are admin / admin123; change the password after the first login. For a test setup, expose only the Web and MQTT TCP 1883 ports to the networks that need them. Do not expose internal database or Redis services directly to the public Internet.

Official guide: FastBee Docker deployment

3. Create an MQTT product and device

In the console, create an MQTT product and add these Thing Model properties:

Identifier Type Access Purpose
temperature Numeric Read-only Show sensor readings
switch Boolean/switch Read and write Receive a command and report the actual switch state

Save and publish the product, then create a device. Record the product ID from the product details (not the product number), device number, MQTT username and password, and the current user ID. Also record the device authorization code if it is enabled for the product.

For a test connection, use:

Host: mqtt://SERVER_IP
Port: 1883
Protocol: MQTT 3.1.1
Client ID: S&DEVICE_NUM&PRODUCT_ID&USER_ID
Username: MQTT username
Password: MQTT password
Enter fullscreen mode Exit fullscreen mode

If device authorization is enabled, use MQTT_PASSWORD&AUTH_CODE as the password. For production, follow the official encrypted-authentication instructions and never commit real credentials to a public repository.

4. Validate the data path with MQTTX

Use MQTTX first to separate broker and topic issues from firmware and wiring issues. Create a connection with the parameters above, then subscribe to the platform-to-device topic:

/{PRODUCT_ID}/{DEVICE_NUM}/function/get
Enter fullscreen mode Exit fullscreen mode

Publish this device information payload:

{
  "rssi": -48,
  "firmwareVersion": 1.0,
  "status": 3,
  "userId": USER_ID
}
Enter fullscreen mode Exit fullscreen mode

Next publish properties to:

/{PRODUCT_ID}/{DEVICE_NUM}/property/post
Enter fullscreen mode Exit fullscreen mode 
[
  {"id":"temperature","value":"23.6","remark":"bench test"},
  {"id":"switch","value":"0","remark":"relay off"}
]
Enter fullscreen mode Exit fullscreen mode

Confirm that the device is online and both values appear in its detail page. Each id must exactly match a Thing Model identifier. Values are strings; Boolean values use "0" or "1". After connecting, publish /info/post first, followed by properties or events.

5. Connect an ESP32 or ESP8266

Option A: FastBee-Arduino on ESP32

For the fastest device-side start, follow the official quick-start guide to select a merged firmware for a supported ESP32 board and flash it with the online tool. Match the firmware to the board’s Flash and PSRAM configuration, then configure Wi-Fi, peripherals, and network settings.

Set the platform address to an IP or hostname reachable from the board. Enter the device identity and MQTT credentials configured for the product. On a local network, the broker is typically SERVER_IP:1883. Configure the temperature sensor and switch output, map them to temperature and switch, and check the device’s online state and property updates in the console.

Official steps: FastBee-Arduino quick start · Hardware and environment

Option B: A custom MQTT client on ESP8266

An ESP8266 can connect as a standard MQTT device, but you must implement and maintain its Arduino firmware adapter. Connect to Wi-Fi and the MQTT 3.1.1 broker with the credentials above, publish device information and properties, and subscribe to /function/get. FastBee-Arduino’s official zero-code firmware is not ESP8266 firmware.

The firmware logic should look like this. Replace mqttPublish, mqttSubscribe, JSON parsing, and GPIO operations with the APIs from your chosen MQTT library:

Connect to Wi-Fi
Connect to MQTT with clientId = "S&" + DEVICE_NUM + "&" + PRODUCT_ID + "&" + USER_ID
Subscribe to /{PRODUCT_ID}/{DEVICE_NUM}/function/get
Publish /{PRODUCT_ID}/{DEVICE_NUM}/info/post

Loop:
  Read temperature
  Publish /{PRODUCT_ID}/{DEVICE_NUM}/property/post
    [{"id":"temperature","value":"23.6","remark":"sample"},
     {"id":"switch","value":"0","remark":"actual state"}]
  On function/get, parse the id and value
  If id is switch: update the output using safe hardware logic, then read actual state
  Publish the actual switch state to property/post
Enter fullscreen mode Exit fullscreen mode

For ESP8266, check GPIO levels, boot-strapping pins, power, and relay-module compatibility. Do not copy pin numbers from a different board. See the official MQTT access guide for the protocol format and topic list.

6. Send a remote command from the platform

In the console’s device detail or control view, set the switch property. The platform publishes a payload like this to the device subscription:

Topic: /{PRODUCT_ID}/{DEVICE_NUM}/function/get
Enter fullscreen mode Exit fullscreen mode 
[{"id":"switch","value":"1","remark":"platform command"}]
Enter fullscreen mode Exit fullscreen mode

The firmware should parse the identifier and value, drive the output, then report the actual state on /property/post:

[{"id":"switch","value":"1","remark":"output confirmed"}]
Enter fullscreen mode Exit fullscreen mode

Do not report the requested value as the device state without verifying execution. If the GPIO write fails, the relay does not move, or the read-back state differs, report the real result so it can be diagnosed. Test with an isolated low-voltage circuit; never connect a development board directly to mains. Relay modules can use different active levels, so confirm the module documentation and default-off behavior before powering it.

7. Acceptance checks and troubleshooting

  • Device is offline: Check that Docker containers are running, TCP 1883 is reachable, and the device is not using localhost as the server address.
  • Authentication fails: Verify the device number, product ID, and user ID in clientId; append the authorization code if the product requires it.
  • Online but no data: Publish the product, check the exact product ID and device number in the topic, send /info/post first, and confirm the property IDs and JSON array format.
  • Command is not received: The device must be online and subscribed to /{PRODUCT_ID}/{DEVICE_NUM}/function/get. Check the console command log and the MQTT subscription.
  • Console says on, hardware stays off: Make the property writable, confirm the firmware handles that identifier, check GPIO and module active level, and report the state after execution.

The minimum successful round trip is: the device appears online, temperature updates, the platform sends switch=1, the device changes its output, and the device reports the actual switch state.

Frequently asked questions

Can I use FastBee-Arduino zero-code firmware on an ESP8266?

No. FastBee-Arduino’s documented zero-code firmware targets supported ESP32 boards. An ESP8266 can use FastBee’s MQTT protocol with a custom firmware client that implements the documented authentication, topics, and payloads.

Does FastBee Open Source include an MQTT broker?

Yes. FastBee’s official Open Source Edition documentation says it includes a Netty-based MQTT Broker. The MQTT guide documents TCP port 1883 and MQTT 3.1.1 for TCP connections.

What does a successful ESP32-to-FastBee test verify?

Verify that the device appears online, reports a Thing Model property, receives a platform command, performs the hardware action, and reports the resulting state. Message delivery alone does not prove that the hardware action succeeded.

What server resources does the FastBee Docker guide specify?

The current official Docker guide lists Docker 20.10+, Docker Compose 2.0+, and a minimum of 2 CPU cores and 4 GB RAM. These are documented deployment prerequisites, not a production capacity guarantee.

Official references

Review the license before deployment or redistribution. FastBee’s official authorization page identifies AGPL-3.0 for the open-source edition and describes its usage boundaries.

Top comments (0)