Home
Welcome to the MiP_ESP8266_Library wiki!
Here you will find all documentation for the MiP_ESP8266_Library. This is a guide to install the required hardware and software and describe all function calls in the API. Function calls are organized into 17 groups identified in the table below and explained in separate pages listed to the right. Below are links to various examples which demonstrate how to use each function in the library.
Table of contents
- 4-pin ZH JST connector with wires.
- The Wemos D1 mini or a compatible board.
- Optional: The D1 mini Pack unless you intend to put the D1 mini in MiP's head.
- 4-pin ZH JST female connector (these come with the JST wires linked above).
- 2x machined female headers, 8-pin.
- Right-angle female pin header, 2-pin.
- An FTDI adapter.
- Arduino IDE.
- The esp8266 Arduino library.
- Python - The guide provided by esp8266 will walk you through the process of installing Python and performing over-the-air (OTA) updates.
- Your favorite telnet program.
MiP is a unique robot in that it must expend energy to stay upright. This unique quality can at times make it difficult to program and debug via serial cable, especially while MiP is moving around. Therefore, in addition to providing debugging over serial line, I have integrated JoaoLopesF's RemoteDebug library which enables debugging over wireless telnet. However, the debugging library in turn is limited to offering output from the Arduino loop() function only. Judiciously using both serial and telnet debugging will aid in the development of your sketch. An example is provided for debugging using telnet.
There are a few excellent guides available on opening MiP and tapping its UART port.
- SparkFun's Hacking the MiP - No need to create a hole in MiP's body (step 6). The D1 mini will fit entirely inside MiP's otherwise empty head once it is connected.
- Macetech's Quick tear-down guide.
- Adamgreen's post, What's inside my MiP.
The MiP D1 mini Pack makes outfitting MiP with a D1 mini a snap. If you are going to use it, follow the directions provided to install it. If you are going to simply pop the D1 mini into MiP's head, read on.
MiP's operating voltage ranges from 4.8 volts using the recharge kit or rechargeable AAA batteries or up to 6 volts using standard alkaline AAA batteries. The D1 mini operates at 3.3 volts. Fortunately, there is an ME6211 onboard that can regulate voltage from a rated maximum of 6 volts down to the 3.3 volts the D1 mini requires. If you are concerned that 6 volts is too high, consider placing a power resistor between MiP and the D1 mini. I use NiMh rechargeable batteries which keep the voltage at a safe maximum of 4.8 volts.
Using the 4-pin JST connector, connect MiP and the D1 mini using the following table. Be sure to note that MiP's transmit line needs to be connected to the D1 mini's receive line and vice versa. Connection on the D1 mini end can be made using solder or pin headers.
| MiP UART | D1 mini or compatible |
|---|---|
| GND | GND |
| RX | D8 (TXD2) |
| TX | D7 (RXD2) |
| VCC6V | 5V |
Note: You may be wondering why we don't connect MiP to the RX and TX pins. They are shared with the USB port which we want to use for programming and power. The API uses Serial.swap() to send commands to and receive responses from MiP using RXD2 and TXD2.
Until OTA updates are enabled, leave the D1 mini outside MiP's case to program the D1 mini using the USB port. During development I leave an arm off and pass the JST cable through the arm hole. Once OTA updates are enabled you can tuck the D1 mini into MiP's head and reassemble MiP, but be careful! OTA support needs to be included with every sketch you upload to MiP. The first time you forget to include the OTA code, you'll need to open MiP again and re-program the D1 mini using its USB connector.
We'll need a way to read MiP's debug output via serial port. The D1 mini provides one full UART which we've already connected to MiP. It also provides the transmit-only half of another UART which is intended for debugging. We'll use it for such here and connect an FTDI adapter to read the output back to your workstation. Consider leaving a pigtail loose through the hole you cut in the battery compartment as described in SparkFun's MiP hacking guide. If you don't, you can still debug MiP but it will be a little more challenging. You won't be able to observe any debug output in setup() and what you observe in loop() will be via telnet only.
| FTDI | D1 mini or compatible |
|---|---|
| GND | GND |
| RX | D4 |
Now that the hardware is connected to MiP, connect the D1 mini to your development workstation using a micro USB cable.
We're all set to program the D1 mini. Launch Arduino IDE, make sure the port number for the D1 mini is selected from Tools->Port and upload the blink sketch from Arduino IDE's examples.
void setup() {
// initialize digital pin LED_BUILTIN as an output.
pinMode(LED_BUILTIN, OUTPUT);
}
// the loop function runs over and over again forever
void loop() {
digitalWrite(LED_BUILTIN, HIGH); // turn the LED on (HIGH is the voltage level)
delay(1000); // wait for a second
digitalWrite(LED_BUILTIN, LOW); // turn the LED off by making the voltage LOW
delay(1000); // wait for a second
}
Working? Great! Now we do the fun stuff. Let's modify the blink sketch to enable Internet-connectivity. While esp8266's guide offers a robust implementation for performing OTA, presented here is the bare minimum sketch to connect MiP to wifi. Be sure to edit the sketch with the access point and password for the network you will connect to. Launch the serial monitor using the COM port for the FTDI adapter that is connected to the D1 mini's debug port prior to programming it so that we can observe the results of the next sketch.
#include <ESP8266WiFi.h> // These three headers are necessary to enable wifi
#include <ESP8266mDNS.h>
#include <WiFiUdp.h>
#include <ArduinoOTA.h> // This header enables OTA
const char* ssid = "............."; // Fill in the SSID for your wifi network
const char* password = "............."; // Fill in the password for your wifi network
// the setup function runs once when you press reset or power the board
void setup() {
// initialize digital pin LED_BUILTIN as an output.
pinMode(LED_BUILTIN, OUTPUT);
Serial1.begin(74880);
WiFi.mode(WIFI_STA);
WiFi.begin(ssid, password);
while (WiFi.waitForConnectResult() != WL_CONNECTED) {
Serial1.println(F("Connection Failed! Rebooting..."));
delay(5000);
ESP.restart();
}
ArduinoOTA.begin();
Serial1.println(F("Ready"));
Serial1.print(F("IP address: "));
Serial1.println(WiFi.localIP());
}
// the loop function runs over and over again forever
void loop() {
ArduinoOTA.handle();
digitalWrite(LED_BUILTIN, HIGH); // turn the LED on (HIGH is the voltage level)
delay(1000); // wait for a second
digitalWrite(LED_BUILTIN, LOW); // turn the LED off by making the voltage LOW
delay(1000); // wait for a second
}
If everything works the serial monitor will show the IP address assigned to MiP. If you have access to your wifi router, check your DHCP assignments. You should see the IP address that was reported in the serial monitor assigned to a device with a name like "ESP_9337DA."
That's it! MiP is now a cloud-connected robot. Next it is time to start reviewing the examples provided below, especially the BareMinimumWifi example which is tailored to configure MiP for our environment and is a good place to start your own sketch. Be sure to read the documentation for the API. Good luck!
These examples are organized into two sections. The first section contains the original, "offline" examples taken from the original ProMini Pack library and describe how to use the API. The second section contains examples illustrating how to employ the wifi capabilities of the D1 mini.
Try the examples below in any order to learn how to use the API.
- ChestLED: Take control of the RGB LED in the chest of the MiP.
- Clap: Send descriptive messages to the Arduino IDE about each clap event deteced by the MiP robot.
- ContinuousDrive: You want to control the motion of the MiP in real time? This is the example for you.
- DisconnectApp: Disconnect all apps, including this sketch and any app that may be connected to Bluetooth.
- DistanceDrive: Tell the MiP robot exactly how far to travel and forget about it.
- DriveForwardBackward: Tell the MiP robot how long to drive forward/backward and forget about it.
- EnableGameMode: Cycle through each of the game modes available.
- EnableMiPDetectionMode: Allow your MiP to be discovered by others.
- FallDown: Tired of standing around? Command MiP to fall flat on his face.
- Gesture: Use your hand to make gestures to MiP. Send descriptive messages about each detected gesture.
- GestureRadarMode: Want to learn more about how to enable/disable IR based gesture and radar measurements? Check out this example.
- GetUp: If MiP falls down, learn how to have him try getting back up on his wheels.
- HeadLEDs: Take control of the four individual eye LEDs in MiP's head.
- Odometer: How far has MiP been traveling around your personal robot laboratory? This example shows you how to find out and reset its measurement.
- PlaySound: Learn how to get MiP robot vocalizing under your control!
- Radar: Is there anything in front of MiP? This example sends descriptive messages when it detects changes in the obstacles around it.
- RawSendReceive: You found a command in WowWee's protocol specification that isn't supported by this library? This example shows you how to experiment with these new commands.
- ReadWriteEeprom: Read and write your own data to MiP's EEPROM. This is useful for storing data across power cycles. See also ZeroEeprom.
- ReadIRDongleCode: Reads IR code sent from another MiP. See also SendIRDongleCode.
- SendIRDongleCode: Sends IR signals to another MiP. See also ReadIRDongleCode.
- SRSdemo: MiP made an appearance at the Seattle Robotics Society meeting on April 21st, 2018. This is a cloud-enabled modification of the original code adamgreen demonstrated at the meeting.
- Shake: Is someone shaking poor little MiP? This example shows you how to detect such rudeness and report it.
- SoftwareHardwareVersion: This example shows you how to peek under the covers and see what hardware / software is running inside MiP.
- Status: Detect changes in MiP's battery level or pose and report them.
- Stop: Danger! Danger! Stop your MiP robot in its tracks before it gets itself into more trouble.
- TurnLeftRight: Tell MiP exactly how many degrees to turn and forget about it.
- Volume: MiP is too loud? Turn down the volume with this example.
- Weight: Detect weight changes in what MiP is carrying and report them.
- ZeroEeprom: Write zeroes to each available byte in EEPROM. See also [ReadWriteEeprom].(https://github.com/Tiogaplanet/MiP_ESP8266_Library/blob/master/examples/ReadWriteEeprom/ReadWriteEeprom.ino).
These examples are designed to walk you through connecting MiP to the cloud. I recommend following them in order.
- BareMinimumWifi: This is the bare minimum sketch you need to get MiP connected to wifi. There is a lot going on in this example but it's all necessary to get connected.
- TelnetDebug: Learn how to debug your wifi sketches using a serial monitor and telnet.
- TimeWifi: Turn MiP into a clock! After reading Network Time Protocol (NTP), MiP flashes the time, one digit at a time, using its head LEDs.
- SPIFFS: The last three examples showed how to connect MiP to the cloud, send debug messages to telnet and download and report the time. Let's now take a break from the wifi stuff and learn how to use the SPI flash file system (SPIFFS). This example writes a password to a file in SPIFFS and then reads in back. If the data that is read from the file matches what was written, MiP's chest LED will turn a violet color.
- WeatherStationWifi: For this example and for each of the next weather station examples I've included a couple files from ThingPulse's esp8266-weather-station library to turn MiP into a weather station. The files included from ThingPulse require sqix78's json-streaming-parser so make sure it's installed in your Arduino IDE. The ESP8266 makes use of ThingPulse's OpenWeatherMap API and sets MiP's chest LED to a color indicating the temperature and animates the eyes in conditions of rain.
- WeatherStationSerialWifi: In the WeatherStationWifi example above, we downloaded a lot of weather data but only used the temperature and weather description data to illuminate MiP's chest and eyes. In this example, all downloaded weather data is written to the ESP8266's debug serial port.
- WeatherStationTelnetWifi: The above example was just a warm-up. This example is very similar to WeatherStationSerialWifi but this time, the weather data will be written to telnet using the library's remote debugging features. Keep your debug serial port monitor open for this one - you'll need the IP address written to the serial port to connect via telnet and view the weather data.
- WeatherStationWebWifi: Here is yet another method of viewing the weather data. This time, the weather data is presented in HTML, viewable from your web browser. Just use your browser to navigate to MiP's IP address to view the data.
- WeatherStationFinalWifi: This last weather station example brings several concepts together to present a so-called "production" version sketch to turn MiP into a full-fledged weather person. As in some real production versions of software, the remote debugging feature is removed. Minimal diagnostic data, such as the IP address, mDNS name and MiP baud rate are written to the serial port. The weather data, meant for the user's consumption is nicely displayed in a dynamic HTML page and accessible using either the IP address, or better yet, the mDNS name. MiP's eyes and chest can be turned on or off with a single clap and if MiP is set upright, it switches into a custom roaming mode.