Advanced User Guide - Seeed-Studio/Wio_Link GitHub Wiki

1. About The Board

Wio Link is designed to simplify your IoT development. It is an ESP8266 based Wi-Fi development board for you to create IoT applications with open-source, plug and play electronics, mobile APPs and RESTful APIs.

  • Input Voltage：Battery holder: 3.4~4.2V; MICRO USB: 5V
  • Output DC Current: VCC: 1000mA MAX
  • Operating Voltage : 3.3V
  • Charge Current: 500mA MAX
  • Flash Memory: 4MByte
  • Size: 55mm*48mm
  • Weight: 26g
  • CE/FCC/IC Certified

2. Status LEDs

The BLUE led is the network status indicating led. It has the following blink patterns:

  • breathing - Under configuration mode
  • blink twice quickly then off 1s - requesting IP address from router
  • blink once quickly then off 1s - connecting to the server
  • on 1s then off 1s - The node is online
  • on constantly - the node is dead for not getting IP or not connecting to server.
  • blink quickly (on 100ms then off 100ms) - OTA

Note: The BLUE led is attached to GPIO2 which is also the TX pin of UART1. When downloading firmware, the UART1 dumps the data transmitting on UART0 by instinct. So the BLUE led will blink while downloading firmware. After startup the GPIO2 will be configured as a GPIO not TX of UART1.

The RED led is another status led which indicates the power status of Grove modules. All the six Grove interface's VCC converge together and can be controlled with GPIO 15. When the node is in deep sleep mode, all the grove modules lose their power too. The RED led will light on when Grove modules are powered and will go off when Grove modules aren't powered.

Note 2: The description here for status leds are not applicable for the hardware in engineering prototype version. For engineering prototype, BLUE and RED reverse.

3. Process of Connecting to Server

Assuming that user has finished the configure operation and Wio Link can join WiFi router now, the following are steps Wio Link will take to connect to the server:

4. Debug Console

The GPIO2 is the TX of UART1 (UART1 only has TX). UART1 is used as the default console of ESP8266 SDK. So the bootloader's debugging messages will be printed at UART1 when booting up.

load 0x40100000, len 1396, room 16
tail 4
chksum 0x89
load 0x3ffe8000, len 776, room 4
tail 4
chksum 0xe8
load 0x3ffe8308, len 540, room 4
tail 8
chksum 0xc0
csum 0xc0

2nd boot version : 1.4(b1)
  SPI Speed      : 40MHz
  SPI Mode       : QIO
  SPI Flash Size & Map: 32Mbit(1024KB+1024KB)
jump to run user1 @ 1000

Rüþ

When the bootloader finished the booting and the firmware took the control, GPIO2 is used to drive the blue led by default (too less GPIOs ESP8266 gives us). But don't worry we still have ways to enable the debugging console, to see the debugging messages printed by the Wio firmware. Those messages are produced during the development of the firmware, but also can be helpful if you're facing some difficulty in configuring or developing.

To enable the debugging console, please follow the steps below:

Step 1 - Prepare the hardware.

Find a usb to serial convertor, connect GPIO2 (indicated by screen silk "2") to the RX pin of the convertor, and also the Ground line.

wio-link-debug-serial

Open your favorite serial port terminal application, and connect the serial port of your usb to serial convertor with baud rate 74880. Test the connection by pressing the RESET button to reboot the Wio device, if everything is correct, you will see the above booting messages in your serial port terminal application. Then we can move on to the step 2.

Step 2 - Enable the firmware to print debugging messages through UART1.

As we said above - the firmware will shut down the debugging printing to spare GPIO2 to drive the blue LED by default. Now we get to recover the ability of debugging printing.

  1. Make sure the version of the firmware >= 1.2. You can easily achieve this by OTA update the Wio device once again.
  2. Turn on the switch of debugging printing. You have two choices to do this.
    • The first is to use the wio-cli if you have Python in your OS and Wi-Fi networking in your computer.
    • The second is to use the raw command via the built-in serial port.

Use the wio-cli

Firstly, please follow the guide in the README page to install wio-cli if you haven't. Then press the CONFIG button over 5 seconds and release it, this will put the Wio device into configuration mode. Now configure your computer's Wi-Fi to connect the SSID exposed from the Wio device, whose name will be like Wio_XXXXXX where XXXXXX is the HEX string of the last three bytes of the MAC address of the Wio device. With this done, open your favorite terminal application, and execute:

wio config --debug on

You will get the response like this which indicates the success of your operation.

Setting success!! Device will reboot!!

Use the raw command via built-in serial port

There's a built-in usb to serial convertor onboard which connects to the UART0 of ESP8266. When the Wio device's put into configuration mode, UART0 acts as a raw command interface. Here we're introducing a few useful commands you may utilize. To use these commands, plug your Wio device to your computer, and connect the serial port with your favorite serial port terminal application and baud rate 115200. Press the CONFIG button over 5 seconds and release it, this will put the Wio device into configuration mode. Now send out one of the following commands:

  • VERSION - This command gets the version of the current firmware.
  • DEBUG - This command gets the status of the debugging printing flag, result will be 0 or 1.
  • ENDEBUG: [0 or 1] - This command sets the debugging printing flag.

Note: The EOL should be \r\n.

Back to the point, to enable the debugging printing, we should send out

ENDEBUG: 1

If the setting takes effect, the serial will response

ok
ok
ok

Finally, one thing should be clarified again that once you enabled the debugging printing, the blue LED will blink randomly (apparently, actually it blinks when UART1 transmits data). Disabling of debugging printing will give back the normal blue LED.

5. Repair Bricked Wio Link

For Windows users, please follow the steps below.

  1. Download files:
  2. Unzip .rar and .zip files
  3. Install the driver for CP2102 ( Windows 7 and later OS may install automatically, if not, download the driver from here)
  4. Open ESP FLASH DOWNLOAD TOOL
  5. Configure like the image below. Please note that the serial port number may be not "COM10" for your computer, it will be different on different computers. In the Device Manager, chose the one looks like "Silicon Labs CP210x USB to UART Bridge".
  6. Click START
  7. Press and hold FUNCTION key, then press RESET key, then release both
  8. The download should begin, if not, please redo step 6~7. Also, make sure the Baud rate matches the COM port bit rate (look under Windows Device Manager -> COM & LPT ports-> Properties -> Port settings).

For Linux and Mac users (plus Windows users who have Python installed), please follow these steps.

  1. Download files:
  2. Unzip files, put all the .bin files in one folder
  3. Install esptool.py. Open your terminal application and execute command - pip install esptool (https://github.com/themadinventor/esptool)
  4. Install the driver for CP2102. Download the driver from here.
  5. Open your terminal application and enter the directory of step 2, and execute the following command. Please Windows users note that the serial port number of Windows isn't "/dev/tty.SLAB_USBtoUART", it should be "COMx" whose full name looks like "Silicon Labs CP210x USB to UART Bridge" in Device Manager.
esptool.py -p /dev/tty.SLAB_USBtoUART -b 230400 write_flash --flash_size 32m-c1 0x0000 bootloader.bin 0x1000 user1.bin 0x101000 user2.bin 0x3fc000 esp_init_data_default.bin 0x3fe000 blank.bin

6. Use Wio Link Offline

6.1 Use Wio Link as Arduino

Please refer to https://github.com/esp8266/Arduino

The board configuration is like this:

One thing must be noticed that the power supply of Grove sockets is controlled by a MOSFET switch which is gated by GPIO 15. So you must pull up GPIO 15 in your Arduino sketch to power on the Grove system:

pinMode(15, OUTPUT);
digitalWrite(15, 1);

6.2 Use Wio Link's SDK and Program in Arduino-Style

The whole project's source code provides a good framework to native program instead of programing directly based on ESP8266's SDK. The benefits are:

  • C++ environment
  • Grove drivers ready
  • Arduino style programing(setup and loop)
  • Non-Makefile modification

Brief Steps

  1. Download the whole project.
  2. Program.
  3. Compile.
  4. Flash.

Now let's start a real practice. In this practice, we will program the Wio Link to read temperature and display the read temperature on an OLED screen, also expose Web of Things APIs for the Grove - Temperature & Humidity sensor to internet.

6.2.1 Download the whole project

If you have git installed, clone the project with the following commands

git clone https://github.com/Seeed-Studio/Wio_Link.git
cd Wio_Link
git submodule init
git submodule update

If you have no git installed, please do the following.

Now enter the working directory users_build/local_user_00000000000000000000.

Install the dependencies.

pip install PyYaml

Use the script to scan all the Grove drivers into a database which will be perceived by the Wio firmware framework.

chmod a+x ../../scan_drivers.py
../../scan_drivers.py -k

The option -k tells scan_drivers.py to skip compiling all the grove drivers into one static library.

Now a file named "drivers.json" will appear in the root directory ../../.

6.2.2 Program

In the working directory, there should be at least one file named Main.cpp. Main.cpp is like the Arduino sketch file. It always consists of two basic functions - setup() and loop(). You can edit Main.cpp to implement these two functions. Also you can create new header files and source files in this directory. The newly created files which suffixed with .h or .cpp extension will automatically be scanned by Makefile. You can use the APIs from ESP's official SDK, also you can use the grove drivers delivered along with the project.

In this practice we will use the delivered grove drivers in two ways.

No.1 is to edit connection_config.json.

This is also how the drag-n-drop configuration works. After being added into connection_config.json, the grove will be virtualized into web of things with many APIs exposed. The Wio Link firmware framework will accept network RPC and call specified functions in grove driver, then print the result of called function to network caller in json format.

No.2 is to use the grove drive as native code.

In this way, you can just copy the files under the grove's folder into users_build/local_user_00000000000000000000, then include the header file in your code and call functions. The makefile will automatically search the files under users_build/local_user_00000000000000000000. In this way, the grove will not be acting as web of things. The grove drivers are only function resources which can be called by your code.

6.2.2.1 Edit connection_config.json

First, let's see an example of connection_config.json file:

{
"board_name": "Wio Link v1.0",
"connections": [
    {"sku": "111020001", "port": "UART0"},
    {"sku": "101020050", "port": "I2C0"}
]
}

The connection_config.json file describes the connection schematic of Wio Link/Node. It consists of two field - board_name and connections.

"board_name" is string value which can be one of "Wio Link v1.0" or "Wio Node v1.0" currently. For this practice we use Wio Link.

"connections" field is a list structure with each item a dictionary structure describes which module is connected to which port. "sku" indicates which module, "port" indicates which port. The value for "sku" can be get by viewing the header file of each grove driver.

For this practice, we use Grove - Temperature & Humidity sensor, so open ../../grove_drivers/grove_temp_hum/grove_temp_hum.h, find the line //SKU 101020019-ffff, we get the value for "sku" - 101020019-ffff. And we're going to plug Grove - Temperature & Humidity to "Digital1" socket of Wio Link, the "port" value for "Digital1" socket is "D1".

Now the content of connection_config.json file is:

{
"board_name": "Wio Link v1.0",
"connections": [
    {"sku": "101020019-ffff", "port": "D1"}
]
}

FYI, the value for "board_name" and "port" be found in ../../boards.json.

6.2.2.2 Edit Main.cpp

As we already configured Grove - Temperature & Humidity in connection_config.json file, the driver for Grove - Temperature & Humidity will then be included during the compiling process. The Wio firmware framework will take charge of the instantiation for the Class of this driver. We can reference to the instance with a variable. To get the name of this variable, we need to to pre-build the project, in which process the script will read in connection_config.json and translate it into C++ source code.

chmod a+x ../../pre_build.py
../../pre_build.py
ls
>> Main.h Main.cpp connection_config.json connection_config.yaml rpc_server_registration.cpp  grove_temp_hum_gen.cpp grove_temp_hum_gen.h

The content of Main.h is

#ifndef __MAIN_H__
#define __MAIN_H__
#include "suli2.h"
#include "grove_temp_hum_gen.h"

extern GroveTempHum *GroveTempHumD1_ins;
#endif

The variable for the instance of Grove - Temperature & Humidity's driver Class is GroveTempHumD1_ins, it's a pointer type. Back to the content of ../../grove_drivers/grove_temp_hum/grove_temp_hum.h, the public functions can be called now.

...
float celsius_degree;
GroveTempHumD1_ins->read_temperature(&celsius_degree);
...

Now let's add in the OLED screen's driver.

cp ../../grove_drivers/grove_oled_12864/* .

Plug Grove - OLED Display 0.96'' to the I2C socket of Wio Link. From the content of ../../boards.json, find I2C interface of Wio Link v1.0 board:

"I2C0": { "type": "I2C", "pinsda": 4, "pinscl": 5 }

Continue to edit Main.cpp

...
#include "grove_oled_12864.h"
...
int pinsda = 4;
int pinscl = 5;
GroveOLED12864 *oled = new GroveOLED12864(pinsda, pinscl);
oled->write_clear();
oled->write_string(0,0,"Temp: ");
...
oled->write_float(0, 6, celsius_degree, 2);

The final Main.cpp:

#include "wio.h"
#include "suli2.h"
#include "Main.h"
#include "grove_oled_12864.h"

int pinsda = 4;
int pinscl = 5;
GroveOLED12864 *oled;

float celsius_degree = 0.0f;

uint32_t last_time;


void setup()
{
    oled = new GroveOLED12864(pinsda, pinscl);
    oled->write_clear();
    oled->write_string(0,0,"Temp: ");
    last_time = millis();
    Serial1.println("setup done");
}

void loop()
{
    uint32_t t = millis();
    if (t - last_time > 2000)
    {
        last_time = t;
        GroveTempHumD1_ins->read_temperature(&celsius_degree);
        oled->write_float(0, 6, celsius_degree, 2);
        Serial1.print("celsius_degree: ");
        Serial1.println(celsius_degree);
    }
}

Programming Notes

  1. Never delay the loop over 20ms, that will cause the watchdog timeout
  2. You can use Serial1.print to print debugging messages, and view the messages through debug console.
6.2.2.3 Compile

First, we need to install the toolchain for ESP8266. Please refer to this chapter: https://github.com/Seeed-Studio/Wio_Link/wiki/Server-Deployment-Guide#21-esp8266-cross-compile-toolchain

There's a python script 'build_firmware.py' which helps to compile the project. build_firmware.py calls make to do the compilation and generates the variables needed by Makefile. It also reads in connection_config.json to determine which grove driver should be compiled and generates required files for compilation based on drivers.json.

By default, build_firmware.py will compile both user1.bin and user2.bin. In some developing cases, you just want to compile user1.bin or user2.bin, you can do this by:

../../build_firmware.py 1
or
../../build_firmware.py 2

In detail the script build_firmware.py accepts several parameters in the order showed below:

../../build_firmware.py APP_NUM USER_ID NODE_SN NODE_NAME

Default values for those parameters:

APP_NUM: ALL

USER_ID: local_user

NODE_SN: 00000000000000000000

NODE_NAME: esp8266_node

Now let's compile the project:

chmod a+x ../../build_firmware.py
../../build_firmware.py

If no fail, user1.bin and user2.bin will be generated.

6.2.2.4 Flash the firmware

Based on the above section "5. Repair Bricked Wio Link", choose the path of user1.bin and user2.bin as the ones in your working directory and only check item user1.bin and item user2.bin.

Another method to flash the firmware for Linux/Mac users is to use the esptool-ck: https://github.com/igrr/esptool-ck

esptool -cp /dev/tty.SLAB_USBtoUART -cd nodemcu -cb 921600 -ca 0x1000 -cf user1.bin -ca 0x101000 -cf user2.bin

With esptool-ck, the reset of Wio Link board will be handled in background.