Class project using FreeRTOS w/ ESP8266. Forked from esp-open-rtos
- WS2812B LED strip
- NodeMCU (ESP8266 / ESP12E)
- MAX31820 temperature sensor
- 4.7K ohm resistor (for MAX31820)
- 220 ohm resistor (for WS2812B)
- Some wires and micro-USB cable
NOTE: Must be on linux to build.
- esp-open-sdk
esp-open-sdk is required to build this project. Head to that link for build instructions. Standlone build is fine. Some of the required dependencies for esp-open-sdk are also needed in this project, namely:
python3
python3-pip
pyserial
->pip3 install pyserial
gcc
,make
- Setup
Clone this repository, create a .local
folder in project root, copy over
example settings, and make edits.
git clone https://github.com/someburner/esp-rtos-tests.git
cd esp-rtos-tests
mkdir -p .local
cp settings.example.mk .local/settings.mk
In particular, OPENSDK_ROOT
, WIFI_SSID
, WIFI_PASS
, and PIXEL_COUNT
will
need to be changed. PIXEL_COUNT
should be set to the number of LEDs on your
WS2812B LED strip.
- Bootloader
Once OPENSDK_ROOT
is set, you can build the bootloader and the project.
You may skip building esptool2 and bootloader (rboot) as their binaries are
included in this repo. But commands to re-generate are included for reference.
# esptool2, required to build bootloader and generate binaries
make mkesptool2 -C examples/cpe439
# bootloader
make -C bootloader/rboot
# clean project
make -C examples/cpe439 clean
# build project
make -C examples/cpe439
Before flashing, make sure hardware is connected. The definitions in
settings.example.mk
are set to be hooked up as follows:
- WS2812B 3.3v -> NodeMCU 3.3v
- WS2812B Data -> 220 ohm -> NodeMCU D7
- WS2812B GND -> NodeMCU GND
- MAX31820 3.3v -> NodeMCU 3.3v
- MAX31820 Data -> NodeMCU D1
- MAX31820 Data -> 4.7K Ohm -> NodeMCU 3.3v
To flash the project, connect NodeMCU to USB and run:
# flash project
make flash -C examples/cpe439 ESPPORT=/dev/ttyUSB0
# if you get permission errors, try this:
sudo chown $(whoami):$(whoami) /dev/ttyUSB0
NOTE: /dev/ttyUSB0
must correspond to the serial port of NodeMCU. Usually
it will be /dev/ttyUSB0
.
With pyserial you can watch UART output with the following command:
python3 -m serial.tools.miniterm --eol CRLF --exit-char 003 /dev/ttyUSB0 500000 --raw -q
protip: Add a line like this in your ~/.bashrc
alias nodemcu='python3 -m serial.tools.miniterm --eol CRLF --exit-char 003 /dev/ttyUSB0 500000 --raw -q'
Then you can bring up serial with just nodemcu
.
Assuming hardware is connected correctly, you can interact with the device via MQTT.
NOTE: Commands assuming mosquitto pub/sub clients are installed. To install:
sudo apt-get install mosquitto-clients
On init, the device immediately begins polling the temperature sensor. These
should be logging out on serial every couple seconds. If they aren't, check
your connections. Once the device is connected to WiFi and MQTT, it will begin
publishing messages on the /cpe439/temp
topic.
To watch these updates come in remotely:
mosquitto_sub -h test.mosquitto.org -t /cpe439/temp
A simple message format is used to send RGB values to the device. Commands should take this form:
r:RRRg:GGGb:BBB~
Replace RRR, GGG, BBB with 0-255. For example, these 3 commands will switch the colors to red, green, and blue respectively:
# red
mosquitto_pub -h test.mosquitto.org -t /cpe439/rgb -m 'r:255g:0b:0~'
# green
mosquitto_pub -h test.mosquitto.org -t /cpe439/rgb -m 'r:0g:255b:0~'
# blue
mosquitto_pub -h test.mosquitto.org -t /cpe439/rgb -m 'r:0g:0b:255~'
The esp-open-rtos build process wiki page has in-depth details of the build process.
examples
contains a range of example projects (one per subdirectory). Check them out!include
contains header files from Espressif RTOS SDK, relating to the binary libraries & Xtensa core.core
contains source & headers for low-level ESP8266 functions & peripherals.core/include/esp
contains useful headers for peripheral access, etc. Minimal to no FreeRTOS dependencies.extras
is a directory that contains optional components that can be added to your project. Most 'extras' components will have a corresponding example in theexamples
directory. Extras include:- mbedtls - mbedTLS is a TLS/SSL library providing up to date secure connectivity and encryption support.
- i2c - software i2c driver (upstream project)
- rboot-ota - OTA support (over-the-air updates) including a TFTP server for receiving updates (for rboot by @raburton)
- bmp180 driver for digital pressure sensor (upstream project)
FreeRTOS
contains FreeRTOS implementation, subdirectory structure is the standard FreeRTOS structure.FreeRTOS/source/portable/esp8266/
contains the ESP8266 port.lwip
contains the lwIP TCP/IP library. See Third Party Libraries wiki page for details.libc
contains the newlib libc. Libc details here.
- FreeRTOS v9.0.0
- Espressif IOT RTOS SDK
- esp-open-sdk
- esptool.py
- lwIP v1.4.1, modified via the esp-lwip project by @kadamski.
- newlib v2.2.0, with patches for xtensa support and locking stubs for thread-safe operation on FreeRTOS.
Binary libraries (inside the lib
dir) are all supplied by Espressif as part of their RTOS SDK. These parts were MIT Licensed.
As part of the esp-open-rtos build process, all binary SDK symbols are prefixed with sdk_
. This makes it easier to differentiate binary & open source code, and also prevents namespace conflicts.
Espressif's RTOS SDK provided a "libssl" based on axTLS. This has been replaced with the more up to date mbedTLS library (see below).
Some binary libraries appear to contain unattributed open source code:
- libnet80211.a & libwpa.a appear to be based on FreeBSD net80211/wpa, or forks of them. (See this issue).
- libudhcp has been removed from esp-open-rtos. It was released with the Espressif RTOS SDK but udhcp is GPL licensed.