As promised in the previous post, we’re going to explore a simple application for the Yellow Development Board this time round. The one thing that this board has plenty of is LEDs. There are half-a-dozen red LEDs and one blue across the bottom of the board, as well as a 5mm RGB LED. So, not surprisingly, we’re going for the “Blinkenlights” option as the first demo. You won’t need an MQTT server or even a working access-point to have this demo work, but the display does get a bit boring quite quickly.
If you have modified your board with the addition of the latching power switch described in the hardware article, this demo will turn itself off after three minutes of run time. If you haven’t added the switch, you’ll have to remove power by pulling one of the batteries out, otherwise it will just keep on running until the batteries are completely depleted.
The code for this first demo is available (with the other demos) in the GitHub repository. The filename is
Initial_Power+LEDs.ino. My preferred environment for compiling ESP8266 programs nowadays is PlatformIO (if you haven’t tried it yet, you should give it a go); it makes compiling programs for multiple different architectures a breeze and you don’t have to worry about shoehorning things in, it just does the right thing. Anyway, the demo programs are basically Arduino-IDE format for the ESP8266, so whether your preferred environment is PlatformIO or Arduino-IDE, they should just work for you (if you’re still in the dark ages, using Espressif’s SDK, you’re on your own!).
In addition to the base demo itself, Over-The-Air update functionality is also built in to each program, so assuming that you have a working network and access point, you should only need to upload to your ESP8266 by serial the very first time, after that you can use the normal Arduino or PlatformIO OTA commands to upload a new demo file.
Note that all of the demos are set up to use a static IP address, netmask, gateway and DNS server. This is to ensure that the ESP starts up as quickly as possible in a real “button” application. The WiFi channel number is also specified, again as part of a fast, robust start-up procedure.
Before compiling any of the demos, you need to go through the
user_config.h file and change all of the default settings in there to match your local network. The specific settings you should be interested in are:-
- LOCATION [optional] Setting this to your general region may help you to find your own results when using a public MQTT server for the later demos.
- STA_SSID [required] Set this to the SSID (name) of your Access Point.
- STA_PASS [required] Set this to the (WiFi network) password requested by your Access Point when connecting.
- WIFI_IPADDR [required] Set this to be the IP address which you want this specific ESP module to use (it is assumed that you know your own network …DO NOT simply choose a random IP).
- WIFI_NETMASK [required] This should be set to use your network specific addressing scheme. Generally, if your IP addresses begin with “192.” you should be okay to leave this as “255.255.255.0”, but if you don’t know, please ask someone who does.
- WIFI_GATEWY [required] This should be set to the IP address of your gateway router.
- WIFI_DNSSRV [required] This should be set to the IP address of your local DNS server.
- WIFI_CHANNEL [required] This is the number of the WiFi channel which your access point is using (and can be between 1 and 14, depending upon where in the world you are).
- MQTT_HOST [required for later demos] See later explanation for this option.
If you don’t know the answer to any of the “WIFI_*” settings, you need to find someone with a better knowledge of your local network and ask them; DO NOT just guess. You could effectively cripple the whole of your local network with a wrong answer to some of these questions.
If you have a good, robust working DHCP server and you don’t care about start-up speed, you might want to convert these programs to use DHCP instead. As this is by far the most common option in ESP8266 programs generally available on the ‘net, I will leave this conversion as an exercise for the reader (it’s quite a bit shorter and simpler than the static address variation used here).
Although MQTT isn’t required for this first demo, I’m going to mention it here anyway, just so you know what some of the options in the
user_config.h file are. The default setting for MQTT_HOST in that file is “broker.hivemq.com”, which is a publicly accessible server in Germany which HiveMQ very kindly make available for testing. HiveMQ also provide a whole bunch of MQTT related resources and services, so please do send any business you can in their direction. Please DO NOT bug them with support requests for these demos; those requests should come to me. Please also note that the HiveMQ server gets -very- busy (it’s not unusual to see in excess of 1,000 concurrently connected clients), so it can be quite difficult to see any output from your specific device on their web dashboard. Please resist the temptation to increase your publishing rate; the server is already busy enough.
If, on the other hand, you have a local MQTT broker (server‡), then you should change the MQTT_HOST option in
user_config.h to point to it specifically from the very start (if you don’t yet have an MQTT server set up, I would recommend the Mosquitto package; it comes with the broker and with two command-line utilities, mosquitto_pub and mosquitto_sub, which allow you to easily publish or subscribe to topics on either your local broker, or any other publicly accessible broker service on the ‘net. Mosquitto is available as an optional package for most Linux variants through the software manager and there’s also a binary package available for Windows).
The MQTT_CLIENT_ID is a symbolic ID used by your ESP8266 when talking to the server. It enables the MQTT broker to differentiate between the dozens of ESP8266 modules which you have connected to your network. The string “ESP8266_%06X” is automatically replaced at run time with a six-digit number created from the unique ESP8266 chip-ID, to provide something like “ESP8266_09C721”. This prevents potential clashes where two (or more) ESPs sharing the same ID would cause each other to be disconnected from the MQTT broker when a new request comes from a different address. This means that if 500 of my closest friends all decide to build the MQTT demo and use the default, publicly addressable HiveMQ server, they should all work perfectly, without trampling over one another.
Finally, note that our ESP client can handle three different topics (only two are defined by default). TOPIC1 is defined as “timestamp” and we become a subscriber to that topic (the HiveMQ broker currently publishes a timestamp every few seconds). TOPIC2 is defined as “Yellow/LDR” and our MQTT demo program will publish regular updates to it. The data published to that topic is the ADC value of the ESP8266 pin with the LDR attached (so the value depends upon the ambient light level).
All of the demo programs, including the non-MQTT version, will print out info to the serial port, including regular LDR value updates.
The mood-light display mode on the Yellow is based on code by “Mike Mc” (Mike McRoberts, author of “Beginning Arduino”). The code uses a 256 entry look-up table to compensate for our weird vision and produce what looks like a linear fade to our eyes. Kudos to Mike for writing such a durable routine, which works very well on the ESP, despite its proclivity for running off and doing WiFi-ish stuff at unpredictable intervals.
Speaking of the need to service WiFi requests and other housekeeping, the reader will notice that there are calls to
yield() sprinkled liberally throughout the code and that there is also an added function,
Ydelay(), which is simply a call to the normal delay function with an additional call to
yield() thrown in. It seems like you can’t call
yield() often enough in any ESP code that could get itself caught in a tight loop.
‡ I use the terms “broker” and “server” interchangeably, but strictly speaking, the “broker” is the MQTT process running on what we loosely refer to as a (hardware) server. Your client devices all connect to and exchange messages with this server. You’re not confused, are you?!?!