ESP32/ESP8266 MQTT Guide: Docker Deployment

IoT Basics · MQTT · ESP32 Practice | FastBee Tech Team | A reproducible IoT development walkthrough: start FastBee Open Source with Docker, configure an MQTT product and thing model, then let an ESP32 or ESP8266 report data and receive remote control commands.

Short answer: Using the FastBee open-source platform as an example, first deploy FastBee Open Source with Docker, create and publish an MQTT product and its thing model, then connect the development board with the device number, product ID, user ID, and MQTT credentials. For ESP32 you can choose a supported firmware build from the official FastBee-Arduino documentation; for ESP8266 you need to write your own MQTT client, implementing authentication, topics, and message formats according to the FastBee documentation.

Who this is for: Developers who are familiar with basic networking and Arduino development and are setting up an IoT platform for the first time. Goal: Take a development board from "connected to Wi-Fi" to "the platform sees the data, sends a command, and the device reports its status after execution". Version note: The official FastBee-Arduino zero-code firmware targets the ESP32 family; ESP8266 can be adapted by writing your own firmware against the MQTT protocol described in this article, and you should not apply the ESP32 firmware directly.

What You Will Get When You Are Done

• A FastBee Open Source test environment running through Docker Compose.
• One MQTT product, one temperature property, and one writable switch property.
• One ESP32 or ESP8266 completing the full loop of coming online, reporting properties, and handling remote commands.

The link between the device and the platform looks like this:

Sensor/relay ↔ ESP32 or ESP8266 ↔ MQTT Broker ↔ FastBee platform ↔ Browser console

1. Prepare the Environment

Hardware and Software

• A server or a local virtual machine. The minimum configuration listed in the current FastBee Docker documentation is 2 CPU cores and 4 GB of memory; this is the minimum deployment requirement and is not the same as production capacity planning.
• Docker 20.10+ and Docker Compose 2.0+.
• An ESP32 development board; an ESP8266 board can also be used for the path where you write your own MQTT client.
• A USB data cable and a Wi-Fi network. Optional: a temperature sensor, a low-voltage LED, or an isolated relay module.
• A browser; MQTTX is optional, for validating the Broker and topics first.

The deployment machine, the development board, and the browser must be able to reach each other over the network. Below, SERVER_IP stands for the address of the host running FastBee, and placeholders such as PRODUCT_ID and DEVICE_NUM stand for the values you create in the console. The MQTT address configured on the device side must be the server IP or domain that the device can actually reach; localhost refers to the device itself and cannot be used to reach another server.

2. Deploy FastBee with Docker

FastBee Open Source includes a built-in MQTT Broker (the message broker that receives and forwards MQTT messages), so no separate EMQX deployment is needed for a first test. The environment requirements listed in the current FastBee Docker documentation are Docker 20.10+, Docker Compose 2.0+, and at least 2 CPU cores and 4 GB of memory. These values are the minimum deployment requirements given in the official documentation; production capacity should be evaluated from the number of devices, the message frequency, and the business load.

Run the official installation command in a Linux host terminal, and choose "open-source edition" when prompted:

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

After the services start, check the container status:

docker ps

Open http://SERVER_IP:80 in a browser. The official initial login credentials are admin / admin123; change the password immediately after the first login. During testing, expose only the Web port and MQTT TCP 1883 to the network segment that needs access; do not expose internal services such as the database and Redis directly to the public internet.

Official deployment documentation: FastBee open-source one-click Docker deployment

3. Create the MQTT Product and Device

In the console, go to product management, create a product whose communication method is MQTT, and then add the following thing model properties. A Thing Model is the unified description of a product's device properties, functions, and events; this example uses a temperature property to receive telemetry and a writable switch property to receive control and report the actual state:

Identifier	Type	Permission	Purpose
temperature	Number	Read-only	Display the sensor temperature
switch	Boolean/switch	Read-write	Receive switch control and report the actual state

After saving, publish the product, and then create a device. Record the Product ID (not the product number), the device number, the MQTT username and password, and the ID of the currently logged-in user from the product detail page. If the product has device authorization code enabled, record that as well.

The MQTT connection parameters for the test phase are:

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

If the product has device authorization code enabled, the password format is MQTT password&device authorization code. For production, use encrypted authentication as described in the official documentation, and do not commit real credentials to a public code repository.

4. Verify the Link with MQTTX First

It is advisable to use MQTTX first to rule out firmware and wiring problems. Create a new connection with the parameters above, and once it connects, subscribe to the platform's downstream topic:

/{PRODUCT_ID}/{DEVICE_NUM}/function/get

Publish the following JSON to the device information topic:

{
  "rssi": -48,
  "firmwareVersion": 1.0,
  "status": 3,
  "userId": USER_ID
}

Then publish a set of properties to the property topic:

Topic: /{PRODUCT_ID}/{DEVICE_NUM}/property/post

[
  {"id":"temperature","value":"23.6","remark":"bench test"},
  {"id":"switch","value":"0","remark":"relay off"}
]

Confirm in the platform's device details that the device is online and that the temperature and switch values appear. A property id must match the thing model identifier exactly; boolean values are passed as the strings "0" / "1". When a device connects for the first time, publish /info/post first, then properties or events.

5. Connect ESP32 and ESP8266

Path A: ESP32 with FastBee-Arduino

If you want to get the device side working first, you can follow the official quick-start documentation to choose the matching merged firmware for a supported ESP32 development board, write it with the online flashing tool, and then configure Wi-Fi, peripherals, and network parameters. The Flash/PSRAM specification must match the development board; for the specific chip and firmware model, refer to the official hardware documentation for your target version.

Configure the platform address as the reachable IP or domain of the deployment host, and fill in the device identity and MQTT credentials according to the platform's product configuration. LAN testing usually uses SERVER_IP:1883. After configuring the temperature sensor and switch output in FastBee-Arduino, confirm that they are associated with the temperature and switch identifiers; then return to the platform's device details to watch it come online and the properties change.

Official steps: FastBee-Arduino Quick Start · Hardware and Environment

Path B: Implement the MQTT Client Yourself on ESP8266

ESP8266 can connect as a generic MQTT device, but you have to maintain the Arduino firmware adaptation yourself: connect to Wi-Fi and an MQTT 3.1.1 Broker, use the authentication parameters above, publish device information and properties, and subscribe to /function/get. The official FastBee-Arduino zero-code firmware is not ESP8266 firmware.

The firmware main loop should follow the logic of the pseudocode below. Replace mqttPublish, mqttSubscribe, JSON parsing, and GPIO operations with the actual APIs of the MQTT library you use:

Connect to Wi-Fi
Connect to MQTT, 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 the temperature
  Publish /{PRODUCT_ID}/{DEVICE_NUM}/property/post
    [{"id":"temperature","value":"23.6","remark":"sample"},
     {"id":"switch","value":"0","remark":"actual state"}]
  After receiving function/get, parse id and value
  If id is switch: update the output following hardware safety logic first, then read the actual state
  Publish the actual switch state to property/post

When using ESP8266, make sure the development board's GPIO levels, boot strap pins, power supply, and relay module match; do not copy the pin numbers of another board. The official protocol format and topic list are in the MQTT access documentation.

6. Send Remote Control from the Platform

On the console's device details or device control page, issue a set for the switch property. The platform sends JSON like the following to the topic the device subscribes to:

Topic: /{PRODUCT_ID}/{DEVICE_NUM}/function/get

[{"id":"switch","value":"1","remark":"platform command"}]

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

[{"id":"switch","value":"1","remark":"output confirmed"}]

Do not simply report the desired value back as the device state: if the GPIO write fails, the relay does not operate, or the state reading is inconsistent, the platform should receive the real result so that it can be diagnosed. Verify only on isolated low-voltage circuits; do not connect the development board directly to mains loads. The active level of a relay module varies by model, so confirm the wiring diagram and the default disconnected state before the first power-up.

7. Acceptance Checklist and Common Faults

• Device offline: Confirm that the Docker containers are running, that port 1883 is reachable, and that the device has not set the server address to localhost.
• Authentication failure: Check the device number, product ID, and user ID in clientId item by item; if the authorization code is enabled, check whether the authorization code is appended to the password.
• Online but no data: Confirm that the product has been published, that the product ID and device number in the topic are correct, that /info/post is published first, that the property IDs match the thing model exactly, and that the payload is a JSON array.
• Platform commands not received: The device must be online and subscribed to /{PRODUCT_ID}/{DEVICE_NUM}/function/get; check the console command log and the MQTT client's subscribed topic.
• The platform shows the device as controlled but the hardware did not change: Check whether the property is configured as writable, whether the firmware handles that ID, whether the GPIO and the module's active level match, and confirm that the device reports the state after execution.

The acceptance criterion for the minimum closed loop is: the device shows as online and the temperature value refreshes; after the platform sends switch=1, the device drives the output and reports the actual switch value back to the platform.

FAQ

Can the FastBee-Arduino zero-code firmware be used directly on ESP8266?

No. The official FastBee-Arduino zero-code firmware targets the ESP32 development boards listed in its documentation. ESP8266 can connect over the FastBee MQTT protocol, but you need to implement and maintain the firmware client yourself and handle authentication, topics, and message formats correctly.

The device shows online, but the platform has no temperature data. What should I check first?

First confirm that the product has been published, that the product ID and device number in the topic are accurate, that /info/post has been published first, that the property topic is /{PRODUCT_ID}/{DEVICE_NUM}/property/post, that the JSON payload is an array, and that every id matches a thing model identifier exactly. Property values should match the corresponding data type; the FastBee MQTT documentation specifies that property values are passed as strings.

Is the official 2 CPU cores and 4 GB of memory enough for production?

That is only the minimum deployment requirement listed in the current FastBee Docker documentation, and production capacity cannot be inferred from it. Production configuration should be evaluated from the number of devices, the reporting frequency, data retention, rule load, and concurrent access, and verified with load tests on the target deployment.

After an MQTT command is sent, how do I confirm that the relay actually operated?

The device side should execute the command, check the actual output state, and then report the result to /property/post. A successful platform send or an MQTT message that arrives does not by itself prove that the relay operated; you also need to design state reading and a safe default state for the specific module.

Official Resources

• FastBee open-source one-click Docker deployment
• FastBee open-source MQTT access
• FastBee-Arduino Quick Start
• FastBee-Arduino hardware and environment
• FastBee open-source documentation home
• Open-source license and authorization

Read the license notes before deploying or doing secondary development; the official FastBee authorization page lists AGPL-3.0 for the open-source edition and explains its scope of use.