ESP8266 NodeMCU for MIT Scratch 2
The aim of this project is giving microcontroller control into hands of kids. The solution is inspired by A4S and Firmata. Scratch or RoboRemo can be used as user interface. ESP4S2 is licensed under GPLv3.
ESP8266 is a cheap microcontroller with built-in WiFi (SoC). See IoT for $10 to execute a "Hello, World!" example. There are a lot of variants, examples are optimized for WeMos D1 mini.
Components:
- ESP8266: microcontroller with built-in WiFi (required)
- NodeMCU firmware (required)
- Controller, written in Lua for executing control commands and providing sensor values (required)
- H-bridge (optional)
- HC-SR04 (optional)
- Scratch 2 Offline Editor: a programming interface (optional)
- Bridge, a Scratch Extension written in Python (required to Scratch)
- Python interpreter (required to Scratch)
- Roboremo: a simple manual control interface on Android (optional)
Example setups:
+----------+
+-------------------------------------+ +--------------+ +-->| HC-SR04 |
| Desktop, Laptop | | +--+ +----------+
| | +--->| Controller |
| +-----------+ +----------+ | | | +--+ +----------+
| | | HTTP | +-----+ +--------------+ +-->| H-bridge |
| | Scratch +------->| Bridge | | WiFi +----------+
| | | | +-----+ +--------------+
| +-----------+ +----------+ | | | | +----------+
| | +--->| Controller +----->| H-bridge |
| | | | +----------+
+-------------------------------------+ +--------------+
+------------------+
| Tablet, Phone |
| | +----------+
| +------------+ | +--------------+ +-->| H-bridge |
| | | | WiFi | +--+ +----------+
| | RoboRemo +--------->| Controller |
| | | | | +--+ +----------+
| +------------+ | +--------------+ +-->| HC-SR04 |
| | +----------+
| |
+------------------+
+----------+
+------------------+ +--------------+ +-->+ HC|SR04 |
| Tablet, Phone | | +--+ +----------+
| | +--->+ Controller |
| +------------+ | | | +--+ +----------+
| | +-----+ +--------------+ +-->+ H|bridge |
| | RoboRemo | | WiFi +----------+
| | +-----+ +--------------+
| +------------+ | | | | +----------+
| | +--->+ Controller +----->+ H|bridge |
| | UDP | | +----------+
+------------------+ broad +--------------+
-cast
Supported Scratch commands:
-
Set network(initNet): Initialize WiFi subnet (only one subnet is supported simultaneously), IP address is a sum of subnet address and device id. -
set pin(pinMode): NodeMCU command(s):gpio.modeorpwm.setup+pwm.start -
digital write pin(digitalWrite): NodeMCU command(s):gpio.write -
analog write pin(analogWrite): NodeMCU command(s):pwm.setduty -
analog write pin pair(analogPairWrite): NodeMCU command(s):pwm.setduty -
tank write pin pair(tankWrite): NodeMCU command(s):pwm.setduty -
servo write pair(servoWrite): NodeMCU command(s):gpio.write -
digital read pin(digitalRead): NodeMCU command(s):gpio.read -
analog read pin(analogRead): NodeMCU command(s):adc.reador custom sensor command -
(reset_all): Reset state machine, NodeMCU command(s):gpio.write,pwm.setduty - - (
poll): return cached values ofdigitalRead,analogRead
Bridge Features:
- Supporting more NodeMCUs in one WiFi network
- Command-line parameters
- Overload protection by state machine (only changes are sent to Controller)
- Overload protection by UDP "ACK" (waiting for processing the earlier sent command, +timeout)
- Overload protection by batch command sending (programmatically configured)
- Overload protection by rare poll and caching digitalRead/analogRead values
- Overload protection by queue size limitation (drop)
- Name resolution (instead of IP address)
- Unit tests
Controller Features:
- Basic digital pin handling (mode, high/low, PWM)
-
analogRead:adc.readregisters value to D16 (virtual) -
analogPairWrite: transform a [-100,+100] value to 2 pins of H-bridge for a DC motor -
tankWrite: transform a joystick value pair ([-100,+100], [-100,+100]) to pins of H-bridge for 2 DC motor -
getName: returns Bridge name - Too small PWM value is overwritten to 0 (for DC motors)
- WiFi station and AP mode
- MAC-based configuration
- Configuration for more networks
- State check for pin mode
- UDP
- Send values back to RoboRemo
- TCP
- Supporting more NodeMCUs in one WiFi network, for Bridge
- Supporting more NodeMCUs in one WiFi network, for Roboremo (UDP broadcast)
- HC-SR04 sensor support
- DHT sensor support
- BMP180 sensor support
Clone or download and extract repository from GitHub. Please read LICENSE.
WeMos D1 mini system has some additional resistors and dedicated pins for shields. These constraints determine a logical pinout:
| ESP-8266 Pin | Pin | WeMos Function | suggested ESP4S2 Function |
|---|---|---|---|
| A0 | A0 | Analog input, max 3.3V input | Analog input |
| GPIO16 | D0 | IO | HC-SR04 Trig |
| GPIO5 | D1 | IO, SCL | I2C for shields |
| GPIO4 | D2 | IO, SDA | I2C for shields |
| GPIO0 | D3 | IO, 10k Pull-up | H-bridge B2 |
| GPIO2 | D4 | IO, BUILTIN_LED 10k Pull-up |
Blue LED DHT Data |
| GPIO14 | D5 | IO, SCK | H-bridge A1 |
| GPIO12 | D6 | IO, MISO | H-bridge A2 |
| GPIO13 | D7 | IO, MOSI | H-bridge B1 |
| GPIO15 | D8 | IO, SS 10k Pull-down |
HC-SR04 Echo + 4k7: 5V-->3.3V voltage divider |
D8 pin works well with Pololu DRV8833 as B2 input, but activates motor B with cheap L9110 at power on. D3 works well with cheap L9110. I2C pins are used by WeMos shields OLED and Motor.
HC-SR04 needs 5V power, Echo pin output is 5V, too (3.3V input is good for Trig). A 4k7 with built-in 10k Pull-down resistor behave as a voltage divider, see: HC-SR04 Ultrasonic Range Sensor on the Raspberry Pi.
Pin D4 is used by WeMos shields DHT and DHT Pro.
Other pinout can also be used.
NodeMCU is an embedded Lua firmware to ESP8266. Firmware can be download from NodeMCU custom builds (builds combined binary). For using H-bridge, PWM module must be selected. For using DHT sensor, DHT module must be selected. Integer build must be used. Firmware can be flashed by esptool.py or NodeMCU Flasher, see Flashing the firmware. Since 1.5.1-master, default baud is 115200 (instead of 9600).
Copy secure.lua.example to secure.lua and edit own WiFi authentication configuration.
Copy config.lua.example to config.lua and edit network configuration. Controller supports more WiFi network configuration, selected by WIFI_CFG_NAME. Controllers are identified by its MAC address. STATION and AP mode are supported. In STATION mode (wifiMode=wifi.STATION), Controller requests an IP address from a WiFi AP (a WiFi router or an ESP8266 in SOFTAP or STATIONAP mode). If WiFi AP is not alive, ip parameter will be used. If static_ip=true, Controller enforces ip as IP address (netmask should be declared, too). In SOFTAP mode (wifiMode=wifi.SOFTAP), NodeMCU runs as WiFi AP and WiFi router is not required for WiFi communication. Other Controllers in this WiFi network should be configured with static IP address (static_ip=true). Sensors with custom feature can be configured in devices.
ESPlorer can be used to upload Lua files to ESP. Upload all *.lua files of directory lua to NodeMCU. After reset, NodeMCU will be ready to receive commands and send back input values.
socat can be used for testing Controller without any GUIs (Scratch, RoboRemo). Socat can be installed on Cygwin and Linux. Anoter famous program, netcat, also can send UDP messages, but cannot send from and receive to same port.
Example for sending commands to a specific IP address (Scratch use case):
socat readline UDP4-DATAGRAM:192.168.10.102:9876,bind=:9877
getName
pinMode 4 1
digitalWrite 4 0
digitalWrite 4 0
Example for sending commands to broadcast address (RoboRemo use case):
socat readline UDP4-DATAGRAM:192.168.10.255:9876,bind=:9877
getName
tank-tower pinMode 4 1
tank-tower digitalWrite 4 0
tank-tower digitalWrite 4 0
There are several online portals, where broadcast address can be calculated, for example: [http://www.subnet-calculator.com/](IP Subnet Calculator).
Bridge requires Python 2.7. Command line options will be printed out by --help parameter.
Python 2.7 can be downloaded and installed from Python Releases for Windows. Example for starting Bridge:
C:\Python27\python.exe -c src\ESP4S2.py
Pyton 2.7 package can be installed to Cygwin. Example for starting Bridge:
src/ESP4S2.py
Pyton 2.7 package installation is described at the Linux distributor. Example for starting Bridge:
src/ESP4S2.py
Install Scratch 2 Offline Editor. Import ESP42S extension description src/ESP4S2.s2e (shift-click on "File" and select "Import Experimental Extension" from the menu). The new extension blocks will appear in the More Blocks palette.
RoboRemo can be installed for Android by Google Play.
To connect RoboRemo to Controller, use "Internet (UDP)" connection. Example for a connection string: 192.168.10.102:9876, where the ip and port was set up in lua/config.lua.
A button should be created for initialize pins. Example init button configuration for a H-bridged DC motor on pins 5, 6 and a LED on pin 4:
- set press action (
\nis also supported instead of Enter):
pinMode 4 1
pinMode 5 3
pinMode 6 3
- repeat: delay, period =
0,only press action
Example on/off button configuration for a LED on pin 4:
- set press action:
digitalWrite 4 1ordigitalWrite 4 0, depending on a pull-up resistor of the pin. - repeat: delay, period =
0,only press action
Example slider for a H-bridged DC motor on pins 5, 6:
- set id:
analogPairWrite 5 6 - set min, max: min =
-100, max =100 - send when released (tricky:
send when moveshould be seen) - set repeat period:
500ms
RoboRemo cannot connect to multiple IP addresses. In this case, the boradcast IP address of subnet can be used. For example, if the subnet is 192.168.10.0/24, the broadcast address is 192.168.10.255. There are several online portals, where broadcast address can be calculated, for example: [http://www.subnet-calculator.com/](IP Subnet Calculator). The command sending to this address will be received by all of Controllers. The target Controller name must be marked by the beginning of the command, for example: tank-tower pinMode 4 1, tank-tower pinMode 4 1, tank-tower digitalWrite 4 1. Without marking the Controller name, all of Controller will execute the command.
After starting Bridge (src/ESP4S2.py) and loading ESP42S extension description (src/ESP4S2.s2e), Scratch is ready to create block programs. The first block which must be executed is the Set network. This block initializes Bridge and requests Controllers to send its names back for name resolution. Example for Set network block: 
, where 192.168.10.0 is the subnet ID and 24 is the subnet mask bits. There are several online portals, where subnet ID and subnet mask bits can be calculated, for example: [http://www.subnet-calculator.com/](IP Subnet Calculator). One second must be wait to collect responses from Controllers, for example: 
.
Pin mode must be set before using a pin (set pin). A block can be executed immediately (E) or with the next (W). More blocks can be bundled to one group until the first E block. The last block of execution bundle must be E. Examples for bundled blocks:
The simplest control block is the digital write pin. See examples for controlling WeMos built-in led:
PWM can be controlled by block analog write pin, for example: 
.
H-bridged DC motors can be controlled by analog write pin pair block, for example: 
. The value must be set in interval [-100, 100].
Values can be used by blocks digital read pin and analog read pin, for example:
It's the "Hello, World!" example of microcontroller world. Built-in blue LED of WeMos is connected to pin 4. Because of built-in pull-up resistor, LED behaves opposite. After starting Controller and Bridge, please create the below project:
Click once on Set network. The 192.168.10.0/24 network will be used for communicating to Bridges. It will be valid until Brigde running. Depending on the network setup (WiFi router, ESP AP), the network can be different.
Click on 
. Block set pin will set pin 4 to OUTPUT.
When o key pressed, pin 4 will be set Low (0). Because of built-in pull-up resistor, LED will be turned on. When x key pressed, pin 4 will be set High (1). Because of built-in pull-up resistor, LED will be turned off.
Click on 
to stop all pins.
This project demonstrates PWM. Because of built-in pull-up resistor on pin 4, LED behaves opposite: it will ligth strongest by setting PWM duty cycle to 0% and LED will be turned off by setting PWM duty cycle 100%. After starting Controller and Bridge, please create the below project:
Click once on Set network. It will be valid until Brigde running.
Click on . Block set pin will set pin 4 to PWM.
Press keys 0, 1, 2, 3, 4 to try PWM duty cycles 0%, 50%, 80%, 95%, 100%.
Click on to stop all pins.
This project demonstrates DC motor control using PWM and H-bridge.