Ameba MicroPython: Getting Started with BW16

Realtek RTL8720DN is a Wi-Fi and Bluetooth IC that supports 2.4GHz and 5GHz dual bands for Wi-Fi communication, and Bluetooth Low Energy (BLE) 5.0. BW16 module is manufactured by B&T, this module is a highly integrated Wi-Fi and Bluetooth module with the RTL8720DN as the main SoC (System on Chip), it can be regarded as an SoC for the Wi-Fi and Bluetooth application with typical SBCs. BW16 board is a development board that integrated with the module. There are 2 BW16 boards, BW16 and BW6-TypeC. BW16 board uses Micro USB connector.

BW16 board

The size of the board is 50.4*25.4(±0.2) mm. It uses Micro USB to supply power, which is common in many smart devices.
Please refer to the following figure and table for the pin diagram and function.

BW16 Pinmap

There are 2 buttons besides USB connector. “RST” button is on the left and “Burn” button is on the right as shown on above figures. Refer the following table for the functions of the buttons.

The Upload Mode is required by board when erase flash or upload firmware.

Introduction to BW16 MicroPython Port

Background Information

MicroPython, by definition, is a lean and efficient Python3 compiler and runtime specially designed for microcontrollers.

MicroPython distinguishes itself from other compilation-based platforms with its powerful method of real-time interaction to Microcontroller through a built-in feature – REPL.

REPL stands for Read-Evaluation-Print-Loop, it is an interactive prompt that you can use to access and control your microcontroller.

REPL has been equipped with other powerful features such as tab completion, line editing, auto-indentation, input history and more. It basically functions like the classic Python IDLE but running on microcontroller.

To use REPL, simply open any serial terminal software (most common ones are teraterm, putty etc.) on your PC and connect to your microcontroller’s serial port, then set baudrate to 115200 before manually reset the board, then you will see >>> MicroPython prompt appear on the terminal. Now you may type in any Python script on REPL as long as it’s support by MicroPython and your microcontroller’s MicroPython port.

Most importantly, try to abuse “help()” function as much as possible to gain more information. For example, upon microcontroller power up and REPL shown, just type

help()
You will see a help page giving you more details about this port; also if you type

help(modules)
it will list out all available builtin modules that are at your disposal

Furthermore, if you want to learn more about a module, such as its API and CONSTANT available, simply type the following code and details of that module will be returned to you,

Let’s take Pin module (GPIO) as an example:

>>> help(Pin)
object <class 'Pin'> is of type type
  id -- 
  init -- 
  value -- 
  off -- 
  on -- 
  low -- 
  high -- 
  toggle -- 
  irq -- 
  board -- <class 'board'>
  IN -- 0
  OUT -- 1
  PULL_NONE -- 0
  PULL_UP -- 1
  PULL_DOWN -- 2
  IRQ_RISING -- 1
  IRQ_FALLING – 2

REPL Hotkeys

• Ctrl + d :
Soft reboot MicroPython will perform software reboot, this is useful when your microcontroller is behaving abnormally. This will also run scripts in ‘boot.py’ once again. Note that this will only reset the MicroPython interpreter not the hardware, all your previously configured hardware will stay the way it is until you manually hard-reset the board.

• Ctrl + e :
Paste mode Paste mode allow you to perform pasting a large trunk of code into REPL at once without executing code line by line. This is useful when you have found a MicroPython library and wish to test it out immediately by copy and paste.

• Ctrl + b :
Normal mode This hotkey will set REPL back to normal mode. This is useful if you are stuck in certain mode and cannot get out.

• Ctrl + c :
Quick cancel This hotkey help you to cancel any input and return a new line.

Setting up Development Environment

Step 1: OS environment

BW16 (RTL8720DN) board currently supports Windows OS 32-bits or 64-bits, Linux OS (Ubuntu) and macOS. To have the best experiences, please use the latest version of OS.

Step 2. Installing the Driver

First, connect the board to computer via Micro USB:

Refer to the pin map and table above, D0 and D1 pins are used for program uploading. However, onboard USB-to-UART module is connected to D4 and D5 which is not able to be directly used for program upload. In order to upload firmware, it suggests that adding an external USB-to-UART module connecting to D0 and D1 as shown in the pin connection below:

Optionally, short the pins indicated below to use the on-board USB:
D1 ––– D5
D0 ––– D4

After connected, the USB driver will be automatically installed. If there is any driver issue of connecting board, please go to http://www.wch-ic.com/downloads/CH341SER_ZIP.html for USB driver. Check the COM Port number in Device Manager for Windows OS user:

Step 3. Installing the necessary tools

On Windows

For windows users, please install a serial terminal software to interact with MicroPython. The most common serial terminals are Tera Term and Putty, here we recommend using Tera Term, which can be downloaded from internet.

For advanced developer who wish to compile MicroPython firmware from scratch, then please be sure to install WSL and Ubuntu. Please take note to only install Version 1 of WSL. For tutorial on how to install WSL. Refer to this website: https://learn.microsoft.com/en-us/windows/wsl/install.

Also, Python3 is required during firmware compilation, so be sure to download the latest Python3 from its official website and have it added as environment variable when asked during installation.

On Linux

For Linux user, please install a serial terminal software of your choice using apt-get install command. Here we recommend using picocom for its lightweight.

For advanced developer interested in developing MicroPython module in C, please make sure the GNU make of at least version 3.82 or newer and Python3 are installed and can be found using terminal.

Uploading Firmware into Ameba

Step 1. Navigate to “Firmware_and_DownloadTool.zip” folder

Go to https://github.com/ambiot/micropython and in the Releases tab you will be able to find the folder as shown in the image below.

Unzip the folder and depending on the OS that is used, locate a file named “Double-Click-Me-to-Upload or “Run_Me_in_Terminal.sh”.

Step 2. Enter UART Download mode

Press and hold “Burn” button, press then release “RST” button and release “Burn” button.

Step 3. Uploading the firmware

Follow the instruction printed on the screen or in the “Readme.md” so that the uploading can be carried out successfully. There is a 5-seconds count down set as a reminder to enter the upload mode. Once the uploading is successful, you will see a line of printed on the screen – “All images are sent successfully”.

Try the First Example

Step 1. Open REPL

REPL stands for Read, Evaluate, Print and Loop, it is the MicroPython’s terminal for user to control the microcontroller. REPL is running on LOG UART, thus we need to open our serial terminal software, in this case, Tera Term to see REPL.

Once Tera Term is opened, select “Serial” like in the picture above and choose your ameba’s serial port using the dropdown list, after that, hit “OK”. If your serial terminal is not configured to 115200 baud rate, now is the time to change it to 115200 and leave the rest of settings as default.

Now that the serial port is connected, press the RESET button once on your ameba and you should see the MicroPython’s welcome page as shown below.

What happened here was that your Ameba first check its calibration data and then boot into MicroPython’s firmware, MicroPython then run the “_boot.py” python script and imported built-in libraries.

Now, you can simply type help() to see more information, and type help(modules) to check all readily available libraries.

Step 2. Run WiFi Scan example

As most of peripherals’ examples requires additional hardware to show the example is working, we will just use WiFi Scan example as our first example and to see how easy it is to control WiFi using MicroPython.

Now, please follow along by copy+paste the following code or manually typing them out into Tera Term and hit “Enter”.

from wireless import WLAN
wifi = WLAN(mode = WLAN.STA)
wifi.scan()

You should be able to see the returned result with all discovered wireless network in your surrounding.

With this, we can be sure that the MicroPython firmware is correctly compiled and installed.