ESP8285 boards

• blkboxme

  blkboxme ESP8285 module
• Itead8285

  Itead8285 module

ESP8266 boards

• ESP01 512K

  ESP01 512K Blue
• ESP01 1M Generic

  ESP01 1M Generic Black
• ESP01S 1M

  ESP01S 1M
• ESP07

  ESP07
• ESP12 e/f

  ESP12 e/f
• Bigtreetech Cloud

  Bigtreetech Cloud
• FYSETC-SD-WIFI

  FYSETC-SD-WIFI
• Bigtreetech WiFi module

  Bigtreetech WiFi module
• Diymore

  Diymore
• Wemos D1 mini

  Wemos D1 mini
• Wemos D1 mini Pro

  Wemos D1 mini Pro
• MKS WiFi Module V1.0 (8 pins)

  MKS WiFi Module V1.0 (8 pins)
• MKS WiFi Module V1.1 (16 pins)

  MKS WiFi Module V1.1 (16 pins)
• Nodemcu V0.8

  Nodemcu V0.8
• Nodemcu V1.0

  Nodemcu V1.0
• SOnOff

  SOnOff

ESP32 boards

• Dev Kit V1

  Dev Kit V1
• Dev Kit C V4

  Dev Kit C V4
• Heltec Dev board

  Heltec Dev board

Arduino IDE

Prepare the development environment

• Please download ide from https://www.arduino.cc/en/software

  Warning

  Please use the Legacy IDE (1.8.X), the Arduino IDE 2.X was not tested and won’t be supported

• Install the esp core according your target:

  • ESP8266

    Warning

    Please use the version 2.5.2 or 2.7.4 only! Do not use any version upper than 2.7.4

  • ESP32

    Warning

    Please use the version 1.0.4 only! Do not use any version upper than 1.0.4, and only use ESP32 board, other ESP32 flavors(C2, S2, S3, etc) are not supported in this version.

• Copy the content of the libraries directory to your arduino library directory.

  Warning

  Do not try any version different than the ones provided, they may not work properly.

Open esp3d/esp3d.ino file in Arduino IDE

ESP3D configuration

Open esp3d/config.h and set features you want.

//Customize ESP3D ////////////////////////////////////////////////////////////////////////
#define ESP8266_MODEL_NAME "ESP8266"
#define ESP8266_MODEL_URL "http://espressif.com/en/products/esp8266/"
#define ESP32_MODEL_NAME "ESP32"
#define ESP32_MODEL_URL "https://www.espressif.com/en/products/hardware/esp-wroom-32/overview"
#define ESP_MODEL_NUMBER "ESP3D 2.1"
#define ESP_MANUFACTURER_NAME "Espressif Systems"
#define ESP_MANUFACTURER_URL "http://espressif.com"
//default name if no mac address is valid
#define ESP_DEFAULT_NAME "MYESP"
//if commented name will follow mac address 3 last digits
//like ESP_XXXXXX (eg:ESP_028E41) to avoid overlap if several ESP3D
#define ESP_HOST_NAME ESP_DEFAULT_NAME

//To allow webupdate using small updater
//#define USE_AS_UPDATER_ONLY

//FEATURES - comment to disable //////////////////////////////////////////////////////////

//WEB_UPDATE_FEATURE: allow to flash fw using web UI
#define WEB_UPDATE_FEATURE

#ifndef USE_AS_UPDATER_ONLY
//Do we use async webserver or not (currntly deprecated do not enable it yet)
//#define ASYNCWEBSERVER

//SERIAL_COMMAND_FEATURE: allow to send command by serial
#define SERIAL_COMMAND_FEATURE

//TCP_IP_DATA_FEATURE: allow to connect serial from TCP/IP
#define TCP_IP_DATA_FEATURE

//NOTIFICATION_FEATURE : allow to push notifications
#define NOTIFICATION_FEATURE

//MKS TFT WIFI support see Wiki for wiring
//#define MKS_TFT_FEATURE

//MDNS_FEATURE: this feature allow  type the name defined
//in web browser by default: http:\\esp8266.local and connect
#define MDNS_FEATURE

//SSDD_FEATURE: this feature is a discovery protocol, supported on Windows out of the box
#define SSDP_FEATURE

//NETBIOS_FEATURE: this feature is a discovery protocol, supported on Windows out of the box
//#define NETBIOS_FEATURE

//CAPTIVE_PORTAL_FEATURE: In SoftAP redirect all unknow call to main page
#define CAPTIVE_PORTAL_FEATURE

//RECOVERY_FEATURE: allow to use GPIO2 pin as hardware reset for EEPROM, add 8s to boot time to let user to jump GPIO2 to GND
//#define RECOVERY_FEATURE

//DIRECT_PIN_FEATURE: allow to access pin using ESP201 command
#define DIRECT_PIN_FEATURE

//ESP_OLED_FEATURE: allow oled screen output
//#define ESP_OLED_FEATURE

//DHT_FEATURE: send update of temperature / humidity based on DHT 11/22
//#define DHT_FEATURE

//AUTHENTICATION_FEATURE: protect pages by login password
//#define AUTHENTICATION_FEATURE

//WS_DATA_FEATURE: allow to connect serial from Websocket
#define WS_DATA_FEATURE

//TIMESTAMP_FEATURE: Time stamp feature on direct SD  files
//#define TIMESTAMP_FEATURE
#endif //USE_AS_UPDATER_ONLY
//Extra features /////////////////////////////////////////////////////////////////////////

//Workaround for Marlin 2.X coldstart
//#define DISABLE_CONNECTING_MSG

//Serial rx buffer size is 256 but can be extended
#define SERIAL_RX_BUFFER_SIZE 512

//Serial Parameters
#define ESP_SERIAL_PARAM SERIAL_8N1

//which serial ESP use to communicate to printer (ESP32 has 3 serials available, ESP8266 only one)
//Uncomment one only
#define USE_SERIAL_0
//For ESP32 Only
//#define USE_SERIAL_1
//#define USE_SERIAL_2

//Pins Definition ////////////////////////////////////////////////////////////////////////
//-1 means use default pins of your board what ever the serial you choose
#define ESP_RX_PIN -1
#define ESP_TX_PIN -1

#ifdef RECOVERY_FEATURE
//pin used to reset setting
#define RESET_CONFIG_PIN 2
#endif

#ifdef DHT_FEATURE
#define ESP_DHT_PIN 2
#endif

//Pins where the screen is connected
#ifdef ESP_OLED_FEATURE
#define OLED_DISPLAY_SSD1306  // OLED Display Type: SSD1306(OLED_DISPLAY_SSD1306) / SH1106(OLED_DISPLAY_SH1106), comment this line out to disable oled
#define OLED_PIN_SDA  4  //5 //SDA;  // i2c SDA Pin
#define OLED_PIN_SCL  15  //4 //SCL;  // i2c SCL Pin
#define OLED_ADDR   0x3c
#define HELTEC_EMBEDDED_PIN 16 //0 to disable
#define OLED_FLIP_VERTICALY 1 //0 to disable
#endif

Configure Flash settings

For ESP8266 with 4MB of flash

• Board: Generic ESP8266 Module
• Upload Speed: 115200
• CPU frequency: 160 MHz
• Flash Size: 4M (2M SPIFFS)
• Flash Mode: DIO
• Flash Frequency: 40Mhz
• Reset Method: CK
• Debug Port: Disabled
• Debug Level: None

For ESP8266 with 1MB of flash (this one may not support Web Update due to limited flash size)

• Board: Generic ESP8266 Module
• Upload Speed: 115200
• CPU frequency: 160 MHz
• Flash Size: 1M (128K SPIFFS)
• Flash Mode: DIO
• Flash Frequency: 40Mhz
• Reset Method: CK
• Debug Port: Disabled
• Debug Level: None

For ESP32 with 4MB of flash

• Board: ESP32 Dev Module
• Upload Speed: 115200
• CPU frequency: 240 MHz
• Flash Frequency: 80Mhz
• Flash Mode: QIO
• Flash Size: 4MB
• Partition Scheme: Default 4MB with SPIFFS
• Core Debug Level: None
• PSRAM: Disabled

Connect your board

Compile and flash your module

Select the port you device is connected to and select Upload from sketch menu to compile and flash.

VSCode & Platformio

Prepare the development environment

• Download and install VSCode

• Add PlatformIO IDE extension to VSCode

Open the ESP3D directory folder in VSCode

The first time you open the project, vscode need to download all necessary files, so be patient

ESP3D configuration

Open esp3d/config.h and set features you want.

//Customize ESP3D ////////////////////////////////////////////////////////////////////////
#define ESP8266_MODEL_NAME "ESP8266"
#define ESP8266_MODEL_URL "http://espressif.com/en/products/esp8266/"
#define ESP32_MODEL_NAME "ESP32"
#define ESP32_MODEL_URL "https://www.espressif.com/en/products/hardware/esp-wroom-32/overview"
#define ESP_MODEL_NUMBER "ESP3D 2.1"
#define ESP_MANUFACTURER_NAME "Espressif Systems"
#define ESP_MANUFACTURER_URL "http://espressif.com"
//default name if no mac address is valid
#define ESP_DEFAULT_NAME "MYESP"
//if commented name will follow mac address 3 last digits
//like ESP_XXXXXX (eg:ESP_028E41) to avoid overlap if several ESP3D
#define ESP_HOST_NAME ESP_DEFAULT_NAME

//To allow webupdate using small updater
//#define USE_AS_UPDATER_ONLY

//FEATURES - comment to disable //////////////////////////////////////////////////////////

//WEB_UPDATE_FEATURE: allow to flash fw using web UI
#define WEB_UPDATE_FEATURE

#ifndef USE_AS_UPDATER_ONLY
//Do we use async webserver or not (currntly deprecated do not enable it yet)
//#define ASYNCWEBSERVER

//SERIAL_COMMAND_FEATURE: allow to send command by serial
#define SERIAL_COMMAND_FEATURE

//TCP_IP_DATA_FEATURE: allow to connect serial from TCP/IP
#define TCP_IP_DATA_FEATURE

//NOTIFICATION_FEATURE : allow to push notifications
#define NOTIFICATION_FEATURE

//MKS TFT WIFI support see Wiki for wiring
//#define MKS_TFT_FEATURE

//MDNS_FEATURE: this feature allow  type the name defined
//in web browser by default: http:\\esp8266.local and connect
#define MDNS_FEATURE

//SSDD_FEATURE: this feature is a discovery protocol, supported on Windows out of the box
#define SSDP_FEATURE

//NETBIOS_FEATURE: this feature is a discovery protocol, supported on Windows out of the box
//#define NETBIOS_FEATURE

//CAPTIVE_PORTAL_FEATURE: In SoftAP redirect all unknow call to main page
#define CAPTIVE_PORTAL_FEATURE

//RECOVERY_FEATURE: allow to use GPIO2 pin as hardware reset for EEPROM, add 8s to boot time to let user to jump GPIO2 to GND
//#define RECOVERY_FEATURE

//DIRECT_PIN_FEATURE: allow to access pin using ESP201 command
#define DIRECT_PIN_FEATURE

//ESP_OLED_FEATURE: allow oled screen output
//#define ESP_OLED_FEATURE

//DHT_FEATURE: send update of temperature / humidity based on DHT 11/22
//#define DHT_FEATURE

//AUTHENTICATION_FEATURE: protect pages by login password
//#define AUTHENTICATION_FEATURE

//WS_DATA_FEATURE: allow to connect serial from Websocket
#define WS_DATA_FEATURE

//TIMESTAMP_FEATURE: Time stamp feature on direct SD  files
//#define TIMESTAMP_FEATURE
#endif //USE_AS_UPDATER_ONLY
//Extra features /////////////////////////////////////////////////////////////////////////

//Workaround for Marlin 2.X coldstart
//#define DISABLE_CONNECTING_MSG

//Serial rx buffer size is 256 but can be extended
#define SERIAL_RX_BUFFER_SIZE 512

//Serial Parameters
#define ESP_SERIAL_PARAM SERIAL_8N1

//which serial ESP use to communicate to printer (ESP32 has 3 serials available, ESP8266 only one)
//Uncomment one only
#define USE_SERIAL_0
//For ESP32 Only
//#define USE_SERIAL_1
//#define USE_SERIAL_2

//Pins Definition ////////////////////////////////////////////////////////////////////////
//-1 means use default pins of your board what ever the serial you choose
#define ESP_RX_PIN -1
#define ESP_TX_PIN -1

#ifdef RECOVERY_FEATURE
//pin used to reset setting
#define RESET_CONFIG_PIN 2
#endif

#ifdef DHT_FEATURE
#define ESP_DHT_PIN 2
#endif

//Pins where the screen is connected
#ifdef ESP_OLED_FEATURE
#define OLED_DISPLAY_SSD1306  // OLED Display Type: SSD1306(OLED_DISPLAY_SSD1306) / SH1106(OLED_DISPLAY_SH1106), comment this line out to disable oled
#define OLED_PIN_SDA  4  //5 //SDA;  // i2c SDA Pin
#define OLED_PIN_SCL  15  //4 //SCL;  // i2c SCL Pin
#define OLED_ADDR   0x3c
#define HELTEC_EMBEDDED_PIN 16 //0 to disable
#define OLED_FLIP_VERTICALY 1 //0 to disable
#endif

Select the target in VSCode

• [env:esp32dev] for ESP32 boards
• [env:esp8266] for ESP8266 boards with 4MB flash
• [env:esp01s_160mhz-2.7.4] for ESP8266 boards with 1MB flash

Connect your board

Compile and flash your module

Use Upload and monitor from the target environment you selected to compile and flash your module.

Hardware connection

Connection between ESP and printer board needs 4 wires:

• ESP Tx needs to connect to Rx on MCU of printer board.
• ESP Rx needs to connect to Tx on MCU of printer board.
• You also need to power supply ESP board with with GND and 3V3 or 5V.

Connecting ESP board to target board

Be aware that ESP MCU is 3.3V on GPIO pin and some target board can be 3.3V and others 5V, so you may not be able to directly connect ESP board to target board.

Disclaimer : this wiki is for reference - you are responsible of your board supporting or not 5V, we are not responsible for any damage of wrong wiring.

ESP32 and ESP8266 MCU are only supporting 3.3V. Power supply them with 5V will likelly fry them immediatelly. As MCU is supplied at 3.3V, Tx and Rx signals will be at 3.3V even when board is supplied with 5V. Wether Rx pin is supporting 5V is controversial so we will keep on the safe side and only take datahseet as reference. It’s not recommended to have any signal (including Rx) be higher than power supply (3.3V here).

There are several points to take care. One should check that

1. MCU1 Tx voltage is lower than MCU2 supply voltage
2. Voh_min of Tx is higher than Vih_min of Rx (to check both ways)
3. Vol_max of Tx is lower than Vil_max of Rx (to check both ways)

1 is mandatory and resistor voltage divider bridge or level shiffter is recommended
2 & 3 are not destructive there is just a slight risk signals are not read correctly. But it will work in most case as the limit values given by datasheets are rarelly met in mild conditions (using near 25°C and low current flowing from Tx to Rx)

For the divider bridge a value of R1=1k and R2=2.2k will be fine. You could also use 10k and 22k or anything near a factor 2.

Connection diagrams for some printers and ESP boards

• Printer motherboards
• Anet A8 boards
• Anycubic i3 mega - Trigorilla 8bit board
• AZSMZ LCD board
• AZSMZ-mini board
• Azteeg X5 mini board
• BIQU KFB2.0 board
• Creality CR10 Ender 3 board
• Creality Ender 4 board
• Davinci 1.0/2.0 board
• Davinci 1.0A board
• MKS boards
• MKS Smoothieware board
• RADDS board
• RAMPS 1.4/Re-ARM board
• Smoothieboard board
• SKR Mini E3 board
• Weedo Tina2 board
• For printer boards not listed here
• ESP boards
• ESP-01
• ESP-01 serial wifi module
• ESP-12E/F
• ESP 12F serial wifi module
• ESP32-Cam
• NodeMCU V2/V3
• Sonoff
• Wemos D1 mini

Printer motherboards

Anet boards up to v1.5

• Step 1

You will also have to unsolder the resistors R52 and R53 – they are zero ohm resistors, and serve no other purpose than connecting the atmega chip directly to the onboard USB to UART converter (the CH340 chip). Do it VERY careful – you don’t want to damage your board. If you don’t feel confident – don’t do it.

• Step 2

Now prepare the printer’s motherboard. It requires a simple modification, that does not interfere with it’s operation afterwards – just solder 3 pin x 2 row male header on J8, and add 2 jumpers (or jumper wires) as shown on the picture:

• Step 3

Connect the ESP to J3 repsecting pinout

For more Info check lokster | space

For connecting version 1.7 Anet boards

Unlike older boards this board does not require you to remove any resistors.
You will have to solder two wires from number 9 and number 10 its recommender to connect these to pin 1 and 2 of J3 connector.

Anycubic i3 mega - Trigorilla 8bit board

To connect the ESP12e to the UART0. (Credits:197-murdock).
(Green = RX, Blue = TX)
5V (buck to 3.3v if directly connect to ESP - most development ESP boards already have this voltage limited built-in - but check!) and GND can be taken from the AUX3 exposed connector.
UART0 is normally used by USB port so don’t use both together - so this hack piggybacks on that same port at UART level.

AZSMZ LCD board

AZSMZ-mini board

If you don’t have the soldering skills to grab the connectors from the unpopulated ethernet connection, you can also get 3.3v and GND from the ISP header (bottom left on the diagram above).

Azteeg X5 mini board

BIQU KFB2.0 board

all in one Ramps1.4/Mega2560 R3 controller based

Creality CR10 Ender 3 board

For the Sanguino based CR-10 and Ender printers you will need to solder to any of the via circled (can also be done in the backside of board), or to the legs of the Arduino or ftdi. Connect TX from the board to RX of Wemos D1 mini and RX from board to TX of Wemos D1 mini. 5v and GND are located in the six pin header next to the LCD connector.

Since soldering might be difficult because the solder points are so close to each other, another option is to scrape off the insulation from the traces on the backside and solder there. Be extra careful not to scrape the surrounding ground plane. You need suitable fine scraping tools for this. The picture below shows an Ender-2 PCB.

Creality Ender 4 board

You will need to solder to small circle, or to the legs of the ATmega2560 (RXD0 pin 2, TXD0 pin 3)

Davinci 1.0/2.0 board

Davinci 1.0A board

Alternate Module placement for increased WiFi range (outside metal chassis, antenna has vertical polarization)

MKS boards

To connect the ESP3D to the MKS GEN v1.2 (but the v1.3 and above 1.4 is the most used today).

An ESP12E with the standard schematics, the two resistor connected to the RX pin are substituted by a 1N4148 diode, like in the Adafruit Huzzah board.

ESP12E is connected to the AUX1

ESP12E RX is connected to the pin NEAR GND of the upper row (Marked TXD on pinout.)
ESP12E TX is connected to the adiacent pin at the end of the upper row (Marked RXD on pinout.)

MKS Smoothieware board

RADDS board

RAMPS 1.4/Re-ARM board

Ramps 1.4 can be used on Arduino Mega (repetier/marlin) and Re-ARM for ramps boards (smoothieware/marlin)

Alternative pins if use Re-ARM (J4/UART port)

Smoothieboard board

SKR Mini E3 board

This board is from Bigtreetech and went through various hardware revisions; all of them still feature a TFT pin header which is where you can tap the TX and RX needed. The wiring below is made with a 1.2 board, but the same applies for the other revisions as well; if you need the exact schematic for your mainboard version, you can check Bigtreetech’s github repository.

You literally cannot miss it because the TFT connector is labeled on the board; you can use dupont connectors for the wiring job, no soldering skills needed as long as your ESP comes with pre soldered headers. Just a heads up: the TFT connector provides 5V DC, so be sure to provide them on the correct ESP pin and, most importantly, if your ESP can work with 5 volts as input. You should also pay attention on the board orientation in the schematic, although I oriented it the same way as the actual picture on the left so it’s easier for you.

Weedo Tina2 board

This printer is also brand labelled as Monoprice MP cadet 3D printer

In marlin this connection is serial port 3.

Note the Mega2560 is 5V powered and ESP is 3V3 powered.

For printer boards not listed here

Vast majority of printers have an USB port that is converted to UART before going to MCU. Many printers also have additional (unused) UART port you can use. When possible, always use the additional port for connecting ESP to printer board. When no additional UART port is available you might use the Tx and Rx lines between USB/UART converter and MCU but it’s recommended to cut (in a reversible way) the line to USB/UART converter to avoid conflicts.

If the board is ATmega based the simplest way to find a usable UART port for the ESP is to open ATmega datasheet.

ESP boards

ESP-01

• Use GPIO2 to ground to reset all settings in hard way - 2-6 sec after boot / not before!! Set GPIO2 to ground before boot change boot mode and go to special boot that do not reach FW. Currently boot take 10 sec - giving 8 seconds to connect GPIO2 to GND and do an hard recovery for settings
• Use GPIO0 to ground to be in update mode

ESP-01 serial wifi module

more info about the Breakout PCB: keyestudio

ESP-12E/F

ESP need 3.3v, it is not 5v tolerant, if printer board use more than 3.3V like 5V on ramps.

you can also use Logic LevelConverter Bi-Directional

In order to flash some ESP12E/F boards via their UART interface, the following pins need to be connected:

• VCC to GPIO2
• GND to GPIO0

This has been tested with ESP-12-E boards labeled “ESP8266 For ESP3D FYSETC.COM”

ESP 12F serial wifi module

ESP-12F based serial wifi module (eg from aliexpress ) contains built in 2-way levelshifter/bi-directional logic level converter. So it can be powered via 5V uart from the target’ motherboard.

• We need to manualy ground the IO0 while powering up to start in flash mode while powering up (there is no switch for that, neither for reset)
• Use FTDI adapter as usb2serial
• Need to see in console/serial monitor boot mode is (1,7).
  • baudrate: 74880
  • rst cause:2, boot mode:(3,7)
• Then flash like other esp based board for esp3d

ESP32-Cam

Note: 5V is power supply input and 3V3 is output from regulator. UART Tx and RX signals will be 3.3V

NodeMCU V2/V3

Sonoff

Relay is connected by GPIO12, it can be handled using ESP201 command:

*Get/Set pin value
[ESP201]P<pin> V<value> [PULLUP=YES RAW=YES]
if no V<value> get P<pin> value
if V<value> 0/1 set INPUT_PULLUP value, but for GPIO16 INPUT_PULLDOWN_16
GPIO1 and GPIO3 cannot be used as they are used for serial
if PULLUP=YES set input pull up, if not set input
if RAW=YES do not set pinmode just read value

So [ESP201]P12 V0 should be off and [ESP201]P12 V1 should be on

Wemos D1 mini

Connection with logic level conveter:

example:

printed cases:

• https://www.thingiverse.com/thing:4128593
• https://www.thingiverse.com/thing:2671591

ESP3D commands

Conventions

Please note all commands are in format [ESPxx]. These first brackets [] are not optional.
Most of the time givin no argument will return current configuration If authentication is on, somme commands will need admin password. They are recognised by the optional argument pwd=<admin password> in command line.

Commands

• Get/change STA SSID
  [ESP100] <SSID> pwd=<admin password>

• Change STA Password
  [ESP101] <Password> pwd=<admin password>

• Get/change Hostname
  [ESP102] <hostname> pwd=<admin password>

• Get/change Wifi mode (STA/AP)
  [ESP103] <mode> pwd=<admin password>

• Get/change STA IP mode (DHCP/STATIC)
  [ESP104] <mode> pwd=<admin password>

• Get/change AP SSID
  [ESP105] <SSID> pwd=<admin password>

• Change AP Password
  [ESP106] <Password> pwd=<admin password>

• Get/change AP IP mode (DHCP/STATIC)
  [ESP107] <mode> pwd=<admin password>

• Get/change wifi state (on/off)
  [ESP110] <state> pwd=<admin password>

• Get current IP
  [ESP111]

• Get/Change hostname
  [ESP112] <hostname>

• Get/Set pin value
  [ESP201] P<pin> V<value> PULLUP=<YES/NO> RAW=<YES/NO> ANALOG=<NO/YES> ANALOG_RANGE=[255/1024] CLEARCHANNELS=<NO/YES} pwd=<admin password>
  if no V get P value
  if V 0/1 set INPUT_PULLUP value, but for GPIO16 INPUT_PULLDOWN_16 GPIO1 and GPIO3 cannot be used as they are used for serial
  if PULLUP=YES set input pull up, if not set input
  if RAW=YES do not set pinmode just read value

• Output to oled column C and line L
  [ESP210] C=<col> L=<line> T=<Text>

• Output to oled line 1
  [ESP211] <Text>

• Output to oled line 2
  [ESP212] <Text>

• Output to oled line 3
  [ESP213] <Text>

• Output to oled line 4
  [ESP214] <Text>

• Delay
  [ESP290] <delayMs> pwd=<admin password>

• Get EEPROM mapping version
  [ESP300]

• Get full EEPROM settings content
  but do not give any passwords can filter if only need wifi or printer [ESP400] <network/printer>

• Set EEPROM setting
  [ESP401] P=<position> T={B | I | S | A} V=<value> pwd=<user/admin password>
T type: B(byte), I(integer/long), S(string), A(IP address / mask)
  P position: address in EEPROM

     Description:        Positions: 
    EP_WIFI_MODE             0    //1 byte = flag
    EP_STA_SSID              1    //33 bytes 32+1 = string  ; warning does not support multibyte char like chinese
    EP_STA_PASSWORD          34   //65 bytes 64 +1 = string ;warning  does not support multibyte char like chinese
    EP_STA_IP_MODE           99   //1 byte = flag
    EP_STA_IP_VALUE          100  //4  bytes xxx.xxx.xxx.xxx
    EP_STA_MASK_VALUE        104  //4  bytes xxx.xxx.xxx.xxx
    EP_STA_GATEWAY_VALUE     108  //4  bytes xxx.xxx.xxx.xxx
    EP_BAUD_RATE             112  //4  bytes = int
    EP_STA_PHY_MODE          116  //1 byte = flag
    EP_SLEEP_MODE            117  //1 byte = flag
    EP_CHANNEL               118  //1 byte = flag
    EP_AUTH_TYPE             119  //1 byte = flag
    EP_SSID_VISIBLE          120  //1 byte = flag
    EP_WEB_PORT              121  //4  bytes = int
    EP_DATA_PORT             125  //4  bytes = int
    EP_OUTPUT_FLAG           129  //1  bytes = flag
    EP_HOSTNAME              130  //33 bytes 32+1 = string  ; warning does  not support multibyte char like chinese
    EP_DHT_INTERVAL          164  //4  bytes = int
    EP_FREE_INT2             168  //4  bytes = int
    EP_FREE_INT3             172  //4  bytes = int
    EP_ADMIN_PWD             176  //21  bytes 20+1 = string  ; warning does  not support multibyte char like chinese
    EP_USER_PWD              197  //21  bytes 20+1 = string  ; warning does  not support multibyte char like chinese
    EP_AP_SSID               218  //33 bytes 32+1 = string  ; warning  does not support multibyte char like chinese
    EP_AP_PASSWORD           251  //65 bytes 64 +1 = string ;warning  does not support multibyte char like chinese
    EP_AP_IP_VALUE           316  //4  bytes xxx.xxx.xxx.xxx
    EP_AP_MASK_VALUE         320  //4  bytes xxx.xxx.xxx.xxx
    EP_AP_GATEWAY_VALUE      324  //4  bytes xxx.xxx.xxx.xxx
    EP_AP_IP_MODE            329  //1 byte = flag
    EP_AP_PHY_MODE           330  //1 byte = flag
    EP_FREE_STRING1          331  //129 bytes 128+1 = string  ; warning  does not support multibyte char like chinese
    EP_DHT_TYPE              460  //1  bytes = flag
    EP_TARGET_FW             461  //1  bytes = flag

• Get available AP list (limited to 30)
  [ESP410]<plain>
  Output is JSON or plain text according parameter

• Get current settings of ESP3D
  [ESP420]<plain>
  Output is JSON or plain text according parameter

• Get/Set ESP mode (RESET, SAFEMODE, CONFIG, RESTART)
  [ESP444] <mode> pwd=<admin password>
  if authentication is on, need admin password for RESET, RESTART and SAFEMODE

• Send GCode with check sum caching right line numbering
  [ESP500] <gcode>

• Send line checksum
  [ESP501] <line>

• Change / Reset password
  [ESP550] <password> pwd=<admin password>
  If no password set it use default one

• Change / Reset user password
  [ESP555] <password> pwd=<admin/user password>
  If no password set it use default one

• Send notification
  [ESP600] <message> pwd=<admin password>

• Set/Get notification settings (type can be NONE, PUSHOVER, EMAIL, LINE)
  [ESP610] type=<type> T1=<token1> T2=<token2> TS=<Settings> pwd=<admin password> Get will give type and settings only not the protected T1/T2

• Read SPIFFS file and send each line to serial
  [ESP700] <filename>

• Format SPIFFS
  [ESP710] FORMAT pwd=<admin password>

• Get SPIFFS total size and used size
  [ESP720]

• Get fw version and basic information
  [ESP800]

• Get fw target
  [ESP801]

• Get state / Set Enable / Disable Serial Communication (state: {ENABLE, DISABLE)
  [ESP900] <state>

Notifications

You can use only one type of notification from the following ones:

• Pushover, which is a pay service

  Please follow this link for more information on how to setup a pushover notification service

• Line, which is a free service

  Please follow this link for more information on how to setup a line notification service

• Email using SMTP and HTTPS

  Please follow this link for more information on how to setup a email notification service

• IFTTT webhook, which is a free service up to 5 applets

  Please follow this link for more information on how to setup a pushover iftt service

How to send message ?

Just add following command in your slicer’s end script, or manualy on your GCODE file:
[ESP600]msg pwd=<admin password>

How to ask printer to send command from file played from SD ?

• on Repetier
  M118 [ESP600]msg

• on Marlin
  M118 P0 [ESP600]msg

• on Smoothieware
  echo [ESP600]msg

API

Web Handlers

/ (GET)

root is the default handler where all files will be served, if no file is defined, it looks for index.html or index.html.gz (compressed) if you call specific file, it will look for the filename and filename.gz (compressed) if no file is defined and there is not index.html(.gz) it will display embedded page another way to show the embedded page is /?forcefallback=yes

/files (GET/POST)

this handler handle all commands for FS, including upload on FS.
possible options/arguments are:

• quiet=yes can be used when you don’t want list files but just upload them
• path=... define the path to the file
• action=... define the action to execute which can be:
  - delete
  delete the file defined by filename=... it will also use path=... to do full path
  - deletedir
  delete the directory defined by filename=... it will also use path=... to do full path
  - createdir create the directory defined by filename=... it will also use path=... to do full path
• <filename>S=... give the size of uploaded file with name, need to be set before file is set in upload, POST only

the output is a json file:

```
{   
    "files":[ //the files list  
        {  
            "name":"index.html.gz", //the name of the file
            "size":"83.46 KB", //the formated size of the file 
            "time":"2022-09-04 11:56:05" //the time when the file was modified last time, this one is optional and depend on (FILESYSTEM_TIMESTAMP_FEATURE)
        },
        {
            "name":"subdir", //the name of the file / directory
            "size":"-1", //the size is -1 because it is a directory
            "time":"" //no time for directories optional as depend on (FILESYSTEM_TIMESTAMP_FEATURE)
        }
    ],
    "path":"/", //current path
    "occupation":"52", //% of occupation
    "status":"subdir created", //status 
    "total":"192.00 KB", //Formated total space of Filesystem
    "used":"100.00 KB" //Formated used space of Filesystem
}
```

/upload_serial (POST)

this handler is for uploading files to printer SD using M28/M29 protocol

/command (GET)

this handler is for all commands the parameter is cmd=... if it is an [ESPXXX] command the answer is the [ESPXXX] response if it is not an [ESPXXX] command the answer is ESP3D says: command forwarded and can be ignored

/login (GET/POST)

this handler is for authentication function if enabled possible options/arguments are:
- DISCONNECT=YES it will clear current session, remove authentication cookie, set status to disconnected and response code to 401 - SUBMIT=YES to login it will need also PASSWORD=... and USER=..., the answer will be 200 if success and 401 if failed if user is already authenticated it can use NEWPASSWORD=... instead of PASSWORD=... to change his password, if successful answer will be returned with code 200, otherwise code will be 500 if change failed or if password format is invalid

/config (GET)

this handler is a shortcut to [ESP420] command in text mode, to get output in json add json=yes

/updatefw (POST)

this handler is for FW upload and update

/description.xml (GET)

this handler is for SSDP if enabled to present device informations

<root xmlns="urn:schemas-upnp-org:device-1-0">
    <specVersion>
        <major>1</major>
        <minor>0</minor>
    </specVersion>
    <URLBase>http://192.168.2.178:80/</URLBase>
    <device>
        <deviceType>urn:schemas-upnp-org:device:upnp:rootdevice:1</deviceType>
        <friendlyName>esp3d</friendlyName>
        <presentationURL>/</presentationURL>
        <serialNumber>52332</serialNumber>
        <modelName>ESP Board</modelName>
        <modelDescription/>
        <modelNumber>ESP3D 3.0</modelNumber>
        <modelURL>https://www.espressif.com/en/products/devkits</modelURL>
        <manufacturer>Espressif Systems</manufacturer>
        <manufacturerURL>https://www.espressif.com</manufacturerURL>
        <UDN>uuid:38323636-4558-4dda-9188-cda0e600cc6c</UDN>
        <serviceList/>
        <iconList/>
    </device>
</root>

Captive portal bypass handlers

to avoid a redirect to index.html and so a refresh of the page, some classic handler have been added so they all go to / handler actually

• /generate_204
• /gconnectivitycheck.gstatic.com
• /fwlink/

Web Socket

Only for WebUI not for bridge data

use subprotocol arduino and web port +1 (e.g: 80+1=>81)

text mode

Reserved messages between webui / ESP Format: <label>:<message>

• from ESP to WebUI

  • CURRENT_ID:<id> Sent when client is connecting, it is the last ID used and become the active ID

  • ACTIVE_ID:<id> Broadcast current active ID, when new client is connecting, client without this is should close, ESP WS Server close all open WS connections but this one also

  • ERROR:<code>:<message> If an error raise when doing upload, it informs client it must stop uploading because sometimes the http answer is not possible, or cannot cancel the upload, this is a workaround as there is no API in current webserver to cancel active upload

  • DHT: <value>C The DHT sensor connected to ESP like DHT22

binary mode

Reserved

• from ESP to WebUI serial stream data from ESP to WebUI

• from WEBUI to ESP
  [Not used]

About SD card

ESP boards

• ESP8285 boards
  • blkboxme
  • Itead8285
• ESP8266 boards
  • ESP01 512K
  • ESP01 1M Generic
  • ESP01S 1M
  • ESP07
  • ESP12 e/f
  • Bigtreetech Cloud
  • FYSETC-SD-WIFI
  • Bigtreetech WiFi module
  • Diymore
  • Wemos D1 mini
  • Wemos D1 mini Pro
  • MKS WiFi Module V1.0 (8 pins)
  • MKS WiFi Module V1.1 (16 pins)
  • Nodemcu V0.8
  • Nodemcu V1.0
  • SOnOff
  • WiFI backpack
  • Azteeg X5 mini WIFI
• ESP32 boards
  • Dev Kit V1
  • Dev Kit C V4
  • TTGO/LILYGO V7 mini
  • Wemos D1 R32
  • TTGO T8
  • Lolin D32 Pro
  • Heltec Dev board
  • TTGO T Display
  • TTGO T96 Oled
  • Bigtreetech ESP32E module
  • Bigtreetech ESP32U module
  • ESP32-Cam
  • Olimex ESP32-Gateway
  • Olimex ESP32-POE
  • WT32-ETH1
• ESP32-Pico boards
  • FYSETC SD-WIFI-PRO
• ESP32-C3 boards
  • ESP-C3-32S-Kit
  • LILYGO T-01C3
  • ESP-C3-Super-Mini
• ESP32-S2 boards
  • LILYGO T8 ESP32-S2 V1.1
  • ESP32-S2-Saola-1
  • Wemos S2 mini
• ESP32-S3 boards
  • DevKitC-1 v1.0
  • DevKitM-1 v1.0
  • Freenove ESP32 S3
  • UICPAL ESP32 S3
  • T-SIMCAM
  • Seeed Studio XIAO ESP32S3 Sense

System boards

• TFT
  • Bigtreetech TFT
    • TFT 35 E3
    • TFT 70
  • Makerbase TFT
    • TFT 32L V4.0
    • TFT 35 V1.0
    • TFT 70 V1.1
• Main boards
  • Anet boards up to v1.5 and 1.7
  • Anycubic i3 mega - Trigorilla 8bit board
  • AZSMZ LCD board
  • AZSMZ mini board
  • Azteeg X5 mini board
  • BIQU KFB2.0 board
  • Bigtreetech Octopus 1.1 board
  • Bigtreetech skr board
  • Bigtreetech skr mini board
  • Bigtreetech skr pro board
  • Creality CR10 Ender 3 board
  • Creality Ender 4 board
  • MKS GEN v1.2 to 1.4 board
  • MKS Robin Nano board
  • MKS SBase board
  • RADDS/Due
  • Ramps / Mega
  • Ramps / re-Arm
  • Smoothieboard
  • Bigtreetech skr board
  • Davinci 1.0/2.0 board
  • Davinci 1.0A board

Arduino IDE

Prepare the development environment

• Please download ide from https://www.arduino.cc/en/software

  Warning

  Please use the Legacy IDE (1.8.X) or the latest Arduino IDE 2.X

• Install the esp core according your target:

  • ESP8266

    Warning

    Please use the version 3.1.1.

  • ESP32

    Warning

    Please use the version 2.0.8.

• Copy the content of the libraries directory and extra libraries directory (according your target ESP8266 or ESP32 ) to your arduino library directory

  Warning

  Do not try any version different than the ones provided, they may not work properly.

Open esp3d/esp3d.ino file in Arduino IDE

ESP3D configuration

Open esp3d/configuration.h and set features you want.

You can also generate it, using the ESP3D configurator, which simplify a lot this step.

/* Setup station as default, use AP mode first if not done
* Note: need both defined to enable it
* Uncomment and edit them to define
*/
//#define STATION_WIFI_SSID "*********"
//#define STATION_WIFI_PASSWORD "*********"

/* You can also use a different config file for SSID/password
* Just save it in same location as this configuration.h
* This file is ignored by github
*/
#if defined __has_include
#  if __has_include ("myconfig.h")
#    include "myconfig.h"
#  endif
#endif

/************************************
*
* Serial Communications
*
* Settings and protocols
*
************************************/

/* Serial Communication protocol
* RAW_SERIAL // Basic serial protocol, without data change
* MKS_SERIAL // This is a MakerBase communication protocol, used with MKS printers and TFT, it encapsulated data in a custom protocol
*/
#define COMMUNICATION_PROTOCOL RAW_SERIAL

/* Main Serial port
* which serial ESP use to communicate to printer (ESP32 has 3 serials available, ESP8266 only 2)
* USE_SERIAL_0 //for ESP8266/32, also used by bootloader output, so consider to make it quiet
* USE_SERIAL_1 //for ESP8266/32
* USE_SERIAL_2 //for ESP32 Only
*/
//Main serial port
#define ESP_SERIAL_OUTPUT USE_SERIAL_0

/* Bridge Serial port (deprecated on esp8266 as second serial is)
* which serial ESP use to bridge to another device (ESP32 has 3 serials available, ESP8266 only 2)
* USE_SERIAL_0 //for ESP8266/32, also used by bootloader output, so consider to make it quiet
* USE_SERIAL_1 //for ESP8266/32
* USE_SERIAL_2 //for ESP32 Only\
* Comment if not used
*/
//#define ESP_SERIAL_BRIDGE_OUTPUT USE_SERIAL_1

/* Serial buffer size
*  Maximum size of the serial buffer
*/
#define SERIAL_RX_BUFFER_SIZE 512

/************************************
*
* Target firmware
*
* Targeted firmware that ESP3D will communicate with
*
************************************/
/* Target firmware (default UNKNOWN_FW can be changed later in settings)
* UNKNOWN_FW
* GRBL
* MARLIN
* SMOOTHIEWARE
* REPETIER
*/
#define DEFAULT_FW UNKNOWN_FW

/************************************
*
* Radio mode of ESP3D
*
* The radio mode ESP3D communicate with the network
*
************************************/

/* Use WiFi
* Enable wifi communications
*/
#define WIFI_FEATURE

/* Use Ethernet
* Enable ethernet communications
*/
//#define ETH_FEATURE

//Ethernet type (Check ETH.h eth_phy_type_t)
//TYPE_ETH_PHY_LAN8720
//TYPE_ETH_PHY_TLK110
//TYPE_ETH_PHY_RTL8201
//TYPE_ETH_PHY_DP83848
//TYPE_ETH_PHY_DM9051
//TYPE_ETH_PHY_KSZ8041
//TYPE_ETH_PHY_KSZ8081
#define ESP3D_ETH_PHY_TYPE TYPE_ETH_PHY_LAN8720

//Ethernet board Clock mode
// MODE_ETH_CLOCK_GPIO0_IN
// MODE_ETH_CLOCK_GPIO0_OUT
// MODE_ETH_CLOCK_GPIO16_OUT
// MODE_ETH_CLOCK_GPIO17_OUT
#define ESP3D_ETH_CLK_MODE MODE_ETH_CLOCK_GPIO17_OUT

//Pins of ethernet board
#define ESP3D_ETH_PHY_POWER_PIN 12
//#define ESP3D_ETH_PHY_MDC_PIN 23
//#define ESP3D_ETH_PHY_MDIO_PIN 18

//Address of ethernet board
//#define ESP3D_ETH_PHY_ADDR 0


/* Use Bluetooth
* Enable serial bluetooth communications
*/
//#define BLUETOOTH_FEATURE

/************************************
*
* Channels of ESP3D
*
* The way ESP3D communicate
*
************************************/

/* Use Web server
* Enable http server
*/
#define HTTP_FEATURE

/* Use telnet server
* Enable telnet light (raw tcp) communications
*/
#define TELNET_FEATURE

/* Use Websocket server
* Enable websocket communications
*/
//#define WS_DATA_FEATURE

// Enable notifications
// Allows to send notifications to the user
#define NOTIFICATION_FEATURE

/* Notification message when online
* The message that will be sent when the ESP is online
*/
#define NOTIFICATION_ESP_ONLINE "Hi, %ESP_NAME% is now online at %ESP_IP%"

/* Notification title message
* The title of notification
*/
#define ESP_NOTIFICATION_TITLE "ESP3D Notification"

/************************************
*
* Discovery methods of ESP3D
*
* The discovery methods of ESP3D
*
************************************/

/* Use captive portal
* Enable captive portal in AP mode
*/
#define CAPTIVE_PORTAL_FEATURE

/* Use mDNS discovery
* This method need `bonjour` protocol on windows, or `avahi` on linux
*/
#define MDNS_FEATURE

/* Use Simple Service Discovery Protocol
* It is supported on Windows out of the box
*/
#define SSDP_FEATURE

/************************************
*
* SSDP Customization settings
*
* Customize your ESP3D
*
************************************/

/* Model name
* Modele name of device
*/
#define ESP_MODEL_NAME "ESP Board"

/* Model number
* Modele number of device
*/
#define ESP_MODEL_NUMBER "ESP3D 3.0"

/* Model url
* Modele url of device
*/
#define ESP_MODEL_URL "https://www.espressif.com/en/products/devkits"

/* Manufacturer name
* Manufacturer name of device
*/
#define ESP_MANUFACTURER_NAME "Espressif Systems"

/* Manufacturer url
* Manufacturer url of device
*/
#define ESP_MANUFACTURER_URL "https://www.espressif.com"

/************************************
*
* Flash filesystem
*
* Filesystem on flash
*
************************************/

/* File system type used by ESP3D
* Type of file system used by ESP3D to store files
* ESP_SPIFFS_FILESYSTEM (Deprecated)
* ESP_FAT_FILESYSTEM (ESP32 only with large partitions)
* ESP_LITTLEFS_FILESYSTEM (Default)
*/
#define FILESYSTEM_FEATURE ESP_LITTLEFS_FILESYSTEM

/* Enable date/time on files
* Set date/time on files using SNTP or last webui connection
*/
//#define FILESYSTEM_TIMESTAMP_FEATURE

/************************************
*
* SD filesystem
*
* Filesystem on SD card
*
************************************/

/* SD card connection
* ESP_NO_SD //(default)
* ESP_DIRECT_SD //Only your ESP board is connected to SDCard
* ESP_SHARED_SD //Printer SD Card is also connected to ESP3D
* Does your system has SD card and how it is connected to your ESP3D
*/
//#define SD_DEVICE_CONNECTION ESP_DIRECT_SD

/* SD card library
* ESP_SD_NATIVE //esp32 / esp8266
* ESP_SDIO      //esp32 only
* ESP_SDFAT2    //esp8266  / esp32
*/
//#define SD_DEVICE ESP_SDFAT2

/* Sdio bit mode
* Mode used by SDIO library 1 bit / 4bits
* SD_ONE_BIT_MODE
* SD_FOUR_BIT_MODE
*/
//#define SDIO_BIT_MODE SD_ONE_BIT_MODE

/* Enable date/time on files
* Set date/time on files using SNTP or last webui connection
*/
//#define SD_TIMESTAMP_FEATURE

/************************************
*
* SD card pins
*
************************************/

/* SD card detect pin
* The pin used to detect SD card
*/
//#define ESP_SD_DETECT_PIN 4

/* SD card detect pin value
* State of SD card detect pin when card is present
*/
//#define ESP_SD_DETECT_VALUE 0

/* SD shared flag pin
* The pin used to enable SD card for ESP board
*/
//#define ESP_FLAG_SHARED_SD_PIN -1

/* SD shared flag pin value
* State of SD card shared pin for ESP board
*/
//#define ESP_FLAG_SHARED_SD_VALUE 0

/* SD card CS pin
* The pin used to select SD card in SPI mode
*/
//#define ESP_SD_CS_PIN 5

/************************************
*
* Remote access
*
* Remote filesystem access
*
************************************/

/* Enable global filesystem
* Allows to access to all filesystems from same location
*/
//#define GLOBAL_FILESYSTEM_FEATURE

/* WebDav access
* Use WebDav to access to your filesystem
* FS_ROOT        //mount all FS, need GLOBAL_FILESYSTEM_FEATURE
* FS_FLASH       //mount Flash FS
* FS_SD          mount SD FS
*/
//#define WEBDAV_FEATURE FS_ROOT

/* FTP access
* Use FTP to access to your filesystem (1 connection only)
* FS_ROOT        //mount all FS, need GLOBAL_FILESYSTEM_FEATURE
* FS_FLASH       //mount Flash FS
* FS_SD          //mount SD FS
*/
//#define FTP_FEATURE FS_ROOT