Connect the ESP8266 module via USB, which should create a serial device such as /dev/ttyUSB0. Modify its permsisions with the command sudo usermod -a -G dialout $USER. Log out and back in for the change to take effect.

After installing the Arduino IDE, configure it as follows:

• In File > Preferences, set Additional Boards Manager URLs to:
  http://arduino.esp8266.com/stable/package_esp8266com_index.json
• Under Tools > Board, select NodeMCU 1.0 (ESP-12E Module).
• Under Tools > Port, select the corresponding serial port (e.g., /dev/ttyUSB0).

Write a test program like the example below:

#define LED_PIN 2
int frame_counter = 0;

void setup() {
    Serial.begin(9600);
    delay(1);
    Serial.println("Initialization complete");
    pinMode(LED_PIN, OUTPUT);
}

void loop() {
    char message_buffer[255];
    sprintf(message_buffer, "Frame: %d", frame_counter);
    Serial.println(message_buffer);

    digitalWrite(LED_PIN, HIGH);
    delay(500);
    digitalWrite(LED_PIN, LOW);
    delay(500);
    frame_counter++;
}

Click Upload to compile and transfer the program to the board.

Firmware Tool Notes

The bundled esptool version in Arduino might be outdated, causing upload failures. You can install an updated version via pip and replace the old one.

pip install esptool
# Locate the new installation path
pip show esptool
cd ~/.arduino15/packages/esp8266/hardware/esp8266/3.1.2/tools
mv esptool esptool_backup
cp ~/anaconda3/lib/python3.7/site-packages/esptool . -r

After replacement, rebuild your project.

Useful esptool commands include:

# Read flash chip information
esptool.py --port /dev/ttyUSB0 --baud 115200 flash_id

# Manually write a binary file to flash
esptool.py --port /dev/ttyUSB0 --baud 115200 write_flash -fm dio 0x00000 ./firmware.bin

MQTT Communication Example

1. Install the PubSubClient library via Sketch > Include Library > Manage Libraries… Search for "PubSubClient" and install the version by Nick O’Leary.
2. Set up an MQTT broker. For testing, you can use a public broker such as broker.emqx.io (TCP port 1883).
3. Use the following code sample to connect and communicate.

#include <ESP8266WiFi.h>
#include <PubSubClient.h>

const char* wifi_ssid = "YourNetworkSSID";
const char* wifi_password = "YourPassword";
const char* mqtt_server = "broker.emqx.io";
const char* mqtt_topic = "esp8266/test";
const int mqtt_port = 1883;

WiFiClient network_client;
PubSubClient mqtt_client(network_client);

void message_received(char* topic, byte* payload, unsigned int length) {
    Serial.print("Topic: ");
    Serial.println(topic);
    Serial.print("Payload: ");
    for (unsigned int i = 0; i < length; i++) {
        Serial.print((char)payload[i]);
    }
    Serial.println("\n---");
}

void setup() {
    Serial.begin(115200);
    WiFi.begin(wifi_ssid, wifi_password);
    while (WiFi.status() != WL_CONNECTED) {
        delay(500);
        Serial.println("Connecting to WiFi...");
    }
    Serial.println("WiFi connected.");

    mqtt_client.setServer(mqtt_server, mqtt_port);
    mqtt_client.setCallback(message_received);

    String client_id = "esp8266-" + String(WiFi.macAddress());
    while (!mqtt_client.connected()) {
        if (mqtt_client.connect(client_id.c_str())) {
            Serial.println("Connected to MQTT broker.");
            mqtt_client.publish(mqtt_topic, "Hello from ESP8266");
            mqtt_client.subscribe(mqtt_topic);
        } else {
            Serial.print("Connection failed, state: ");
            Serial.println(mqtt_client.state());
            delay(2000);
        }
    }
}

void loop() {
    mqtt_client.loop();
}

When a message is sent to the subscribed topic from an MQTT client, the serial monitor will display the received content.

Flash Mode Reference

The -fm (flash mode) parameter in esptool is typically set to qio for many ESP-01/07 modules (512 KB). For ESP8266 ESP-12 modules (≥4 MB) and many ESP32 boards, use dio. The ESP8285 usually requires dout.