Overview

The Boilerboard is custom development board that is debuting at Boilermake VI. It is built around an ESP8266-12E, which is a low-cost wifi module. It is flashed with Micropython which is an implementation of Python 3 that is optimised to run on microcontrollers. It is based on the popular Node-MCU boards with some extra features. Notably, an OLED screen and IO expander connected to an I2C bus and a AA power supply.

Getting to Know Your Board

Front Side

pinout

  • Mini USB Connector: use for connecting to your computer, for programming, viewing repl, flashing, etc
  • Power Switch: enables the board to be powered from the battery packs
  • GPIO Pins: use for interfacing with external sensors and other devices
  • Reset Button: resets the board
  • 2 LEDS: D1 is connected to pin 16 and D3 is connected to the IO expander
  • OLED Display: 128X64 pixel oled display
  • 7 Input Buttons: all connected to IO expander

Back Side

pinout

  • ESP8266-12E: “brain” of the board, wifi enabled
  • USB to Serial: converts data from usb to TX and RX signals for the ESP8266
  • Battery Regulator: boosts and regulates voltage from batteries to 3.3V
  • USB Regulator: regulates the 5V from USB to 3.3V
  • IO Expander: I2C device that expands the IO capability, used for the 7 buttons and D3
  • 2 Battery Packs: packs are in in parallel, both total to 3V (later boosted to 3.3V)

Connecting to the Board

Just like how you can open a REPL with Python, you can also open a REPL with Micropython. The method of doing so is very different due to the fact that Python (Micropython) is installed on the microcontroller, versus your computer.

Start by connecting the board to your computer using a mini usb cable.

Check the Port

MacOSX and Linux

To check for the port of the connected device, enter the following command in your terminal:

ls /dev

This will list all of your device files. To figure out which one is the board simply look for the new device when you connect it versus before it was connected. On Linux this will usually be called ttyUSB0.

Windows

To check for the port of the connected device, open “device manager” and expand the “Ports (COM and LPT)” section. The new device that appears when you connect your board to the computer is the port of your board.

It should be “COM” followed by an integer e.g. COM7.

Connect to Board

If you are using MacOSX or Linux we reccommend you install a program called picocom using your appropriate package manager. If you are using Windows, install Putty.

MacOSX and Linux

To connect to the board enter the following command in a terminal, replacing ttyUSB0 if necessary with the port of the board which was determined above:

picocom -b 115200 -p /dev/ttyUSB0

Hit the enter key a few times. If you hit the enter key a few times. You will know you have successfully opened a REPL when you start seeing lines in the terminal starting with >>>.

Windows

Open Putty and select the “Serial” radio button. In the “Serial Line” field, enter the port of the device that was determined above (should be “COM” followed by an integer). In the “Speed” field enter the number: 115200. Click on the “Open” button to open communication with the board.

A new window should open. If you hit the enter key a few times. You will know you have successfully opened a REPL when you start seeing lines in the terminal starting with >>>.

Hello World

Now that you have opened a REPL you can start writing some code. Print statements work the same in Micropython as in Python. Simply enter the following command in your Micropython REPL to execute a Hello World.

print('Hello World')

Now for a second test we will make an LED blink 10 times. To do this we will need to import Pin from the machine library as shown below. Pin will allow us to access the GPIO from the ESP8266.

from machine import Pin
import time

On the Boilerboard there is a LED (D1) on GPIO16. In the cell below we will declare this pin as an output and set it to the variable led.

led = Pin(16, Pin.OUT)

To blink the led 10 times we will make a for loop using Python/Micropython syntax.

for _ in range(10):
    led.value(0)
    time.sleep_ms(500)
    led.value(1)
    time.sleep_ms(500)

If you see the LED blinking after executing the code above, you are ready start developing for the board! Continue to the section below to see how you can upload files to the board.

Getting Files on the Board

For this section you will need a program called ampy to send files to and from the Boilerboard. You can install it using pip:

pip3 install adafruit-ampy

For more information check out ampy on Github.

Lets make a file to send to the board using ampy. A board running Micropython firmware will first look for a file called boot.py and run it first, then it will look for a file called main.py and run that.

In our file let’s simply make an led continuously blink. In your text editor of choice, create a new file and name it main.py. Insert the code from the cell below into that file.

from machine import Pin
import time

led = Pin(16, Pin.OUT)

while True:
    led.value(0)
    time.sleep_ms(500)
    led.value(1)
    time.sleep_ms(500)

Make sure to close the REPL whenever you use ampy. If you do not close the REPL, the following command will not work. Now in a terminal, navigate to the directory of this file and enter the following ampy command. You will need to know the port of your board to do this. See above on how to check this if you do not know it. Remember that on windows the port is in the format COMX. Simply replace /dev/ttyUSB0 with that port name.

ampy -b 115200 -p /dev/ttyUSB0 put main.py

Be aware of what you are doing when you use this. If you overwrite a file that you needed you will lose it and there is no way of recovering it.

After you execute the ampy command, press the reset button on your board. If you see the led start to blink, then you have successfully sent a file to the board.

Now lets open the REPL again on the board. Refer to the “Connecting to Board” section to do this. This time if you hit enter, you will not see >>>. This is because your main.py file is already runnning on the board. You can cancel it by entering Ctrl+c with the REPL window active and then you will see the open prompt with >>>.

If you wish to see the files that you put on your board, enter the code in the cell below into the REPL.

import os
os.listdir()

You should see your main.py file that you put on the board with ampy. This is a useful command for seeing what files are on the board when you are testing your project.

Additional ampy Commands to Know

Remove a file from board:

ampy -b 115200 -p /dev/ttyUSB0 rm file.py

Get a file from board:

ampy -b 115200 -p /dev/ttyUSB0 get file.py

List files on the board:

ampy -b 115200 -p /dev/ttyUSB0 ls

General Tips

  • It is a good idea to be connected to your board when you are testing your code. This is because when connected to your board, if your program crashes it will output the error message through the connection so that you can see it. Additionally any print statements in your code will printed through the connection.