Push OTA Updates to your RAK Wireless Ameba Devices

Introduction:

The Ameba IoT SDK is an awesome piece of core components and APIs to access the features of the Realtek based IoT wifi chipsets like the 8710, 8711 and 8195. The Ameba board are cost effective and the best bang for buck processor out there for wifi IoT projects joining the band wagon with their competitors like Espressif and Nordic.

RAK Wireless has a plethora of board based on these chipsets that cater to various needs of a developer. The RAK 473 and Creator Pro boards are based out of the 8711 mode while the Creator board is based on the 8710 module. The whole family of boards is programmable using the Ameba Arduino IDE and has the same Arduino style APIs that we have come to love

For steps on how to setup you ameba SDK arduino IDE follow the steps in the hackster.io article here: https://www.hackster.io/naresh-krish/diy-remote-wifi-switch-using-the-rak-dashbutton-09b0de

For delving deeper into the AMeba arduino SDK and the Ameba SDK core visit:

• Website: https://www.amebaiot.com/en/

• Examples: https://www.amebaiot.com/en/ameba-sdk-peripherals-examples/

• Git: https://github.com/Ameba8195/Arduino

We will consider the RAK creator pro board for our example here. But the steps are the same for a bare bones RAK 473 or a dash button hardware as well. After setting up your IDE continue to the next step.

Connecting the board:

Once you have installed the Mbed drivers for the RAK creator pro. Connect the Creator pro board to your pc via USB. A MBED drive will be visible with a HTML file and few other files in it. Close this drive and open up the Ameba Arduino SDK.

Add the code below:

/* 
 Author Naresh Krish 
 This arduino program shows how to update AmebaIOT image via Arduino IDE. 
  1) Upload the sketch to the creator pro baord for the first time and Reset the board Ameba.  
  2) Part of the code starts an mdns service called " MyAmeba". Ideally the version of sketc is version 1 
  3) Now edit this sketch. (Ex. the version number) and then reupload, this time instead of choosing USB port,  
    use the IP based port that will show up in the port meny in the arduino IDE 
  4) Once done Ameba would reboot. Check the serial port for the changes (eg version). 
*/ 
#include <WiFi.h> 
#include <OTA.h> 
char nw_ssid[] = "xxxxx";     //  your network SSID (name) 
char pass[] = "xxxxx";  // your network password 
char mDNS_NAME[] = "AmebaIoT"; 
#define FW_REV 1 
#define FW_OTA_PORT 8888 
/** 
* Here we define the recovery pins for the board 
* for the 8195/8711 its 18 and and for 8710 its 17 
*/ 
#if defined(BOARD_RTL8195A) 
#define RECOVER_PIN 18 
#elif defined(BOARD_RTL8710) 
#define RECOVER_PIN 17 
#else 
#define RECOVER_PIN 18 
#endif 
void setup() { 
 //set the mdns name for the board to publish here. 
 //output the version number of the firmware here: 
 printf("Firmware revision version: %d\r\n\r\n", FW_REV); 
 printf("Connect to %s\r\n", nw_ssid); 
 //wait for wifi to get connected to the access point you specifi 
 while (WiFi.begin(nw_ssid, pass) != WL_CONNECTED) { 
   printf("Couldnt connect to ssid...\r\n"); 
   //wait for a second before retrying... 
   delay(1000); 
 } 
 //if connected print the success.... 
 printf("Successfully Connected to %s\r\n", nw_ssid); 
 // These setting are mostly one time setting. We dont need it to be built into the future versions code 
 #if FW_REV == 1 
 // Set the recovery pin .  
 //Boot device with pull up this pin (Eq. connect pin to 3.3V) to recover to firmware rev 1 (forctory firmware) 
 OTA.setRecoverPin(RECOVER_PIN); 
 // This set the flash address that store the OTA image.  
 // Default value is DEFAULT_OTA_ADDRESS 
 OTA.setOtaAddress(DEFAULT_OTA_ADDRESS); 
 #endif 
 // Broadcast mDNS service at OTA_PORT that makes Arduino IDE find Ameba device 
 OTA.beginArduinoMdnsService(mDNS_NAME, FW_OTA_PORT); 
 // Listen at OTA_PORT and wait for client (Eq. Arduino IDE). Client would send OTA image and make a update. 
 if (OTA.beginLocal(FW_OTA_PORT) < 0) { 
   printf("OTA firmware upload failed!!\r\n"); 
 } 
} 
void loop() { 
 Serial.begin(9600); 
 /** 
  * Any user code here. Make sure the firmware code is just half of the programmable flash size  
  * (excluding bootloader, and other sections of flash). 
  * as the chip would store two firmwares, one latest and one for factory reset. 
  */ 
 delay(1000); 
} 

The code is well commented and explains what each function of the OTA.h API does

Click upload in the arduino IDE after selecting the correct board (RTL8711) and the port on the IDE. The program above assumes the the first version of the firmware flash via the USB method (also know as DAP).

The DashUploader project

The DashUploader project is a completely open source implementation of the OTA firmware delivery method for any Ameba IoT board. I maintain the source code over at Github. The project will manifest as an android app and as a cloud service in the future to push updates to several devices. For now the project provides a windows and linux app for pushing new firmware to your Ameba IoT device via a native app.

Git: https://github.com/narioinc/DashUploader-app

A short explanation of the OTA method (courtesy; amebaiot.com):

OTA (Over-The-Air) refers to the online upgrade mechanism via Internet. Arduino IDE offers OTA feature, which follows the workflow in the figure below:

• (i) Arduino IDE searches via mDNS for devices with Arduino IDE OTA service in local network.

• (ii) Since mDNS service is running on Ameba, Ameba responds to the mDNS search and opens the specific TCP port for connection.

• (iii) User develops program in Arduino IDE. When complete, choose network port.

• (iv) Click upload.

Then Arduino IDE sends the OTA image to Ameba through TCP, Ameba saves the image to specific address and sets boot option to boot from this image next time. The workflow consists of three parts: mDNS, TCP and OTA image process. Details related to mDNS is described in the mDNS tutorial. TCP socket programming is used in transferring image, and is already provided in the OTA API. In the next section, we will discuss on how to process the OTA image, and introduce some basic knowledge on Ameba flash memory layout and boot flow.

Ameba Flash Memory Layout

The flash memory size of Ameba RTL8195A is 2MB, ranges from 0x00000000 to 0x00200000. However, the flash memory size of Ameba RTL8710 is 1MB. To fit the use of different boards, we assume the flash memory layout is 1MB. As shown in the figure below, Ameba program occupies three parts of the flash memory:

• Boot Image：That is, the bootloader. When Ameba boots up, it places the boot image to memory and performs initialization. Furthermore, it determines where to proceed after the bootloader. Bootloader looks at the OTA address and recovery pin in system data area and determines which image will be executed afterwards. At the end of the bootloader, it places the image to memory and proceeds to execute it.

• Default Image 2：The developer code is placed in this part, the address starts from 0x0000B000. The first 16 bytes are the image header, 0x0000B008~0x0000B00F comprises the Signature, which is used to verify whether the image is valid. The signature field has two valid values to distinguish the new image from the old image.

• OTA Image：The data in this part is also developer code. By default, this part of memory starts from 0x00080000 (can be changed). The main differences between OTA image and Default Image 2 are the flash memory address and Signature value.

• Boot Flow:

Below figure shows the boot flow:

We discuss the following scenarios:

• (i) OTA is not used, use DAP to upload program: In this situation, bootloader checks the signature of default image 2 and OTA address. Since the OTA address is removed, default image 2 will be selected to execute.

• (ii) OTA image is transferred to Ameba, OTA address is set correctly, recovery pin is not set： Ameba has received updated image via OTA, the signature of default image 2 would be set to old signature. Bootloader checks the signature of default image 2 and OTA address. It will find the OTA address contains a valid OTA image. Since the recovery pin is not set, it chooses the new image (i.e., OTA image) to be executed.

• (iii) OTA image is transferred to Ameba, OTA address is set correctly, recovery pin is set： Ameba has received updated image via OTA, the signature of default image 2 would be set to old signature. Bootloader checks the signature of default image 2 and OTA address. It will find the OTA address contains a valid OTA image. Then check the recovery pin value. If recovery pin is connected to LOW, the new image (i.e., OTA image) will be executed. If recovery pin is connected to HIGH, the old image (i.e., default image 2) will be executed.

Reset pin:

The rak 473 board has a number of digital pins that can be used as the reset pin for our code:

The digital pins by GPIOA, B and C ports are all available for the reset pin. Configure the pin correctly in the arduino sketch above for the factory reset feature to work better.

The app:

Download the binary here: https://github.com/narioinc/DashUploader-app/blob/master/dashuploader-win32-x64.zip?raw=true

The DashUploader app was developed ground up with ease of use rather than complicated collection of menu and convoluted workflows. The apps sole purpose is to assist you to update your Ameba board in three easy steps:

• The first entry shows the device that is transmitting its mdns service. The app auto magically detects any nearby devices waiting for an OTA upgrade. IF your board doesn't show up in 5-10 seconds, press the reset button and wait. Support for selecting multiple board will be release in BETA v1.1.

• Once your devices shows up, its time to push your OTA.bin file to the board. click Browse... and select your boards ota.bin file that contains the firmware.

• Now, click Upload. The app uploads to the board successfully. It will show an OTA success. If you would like to update another board, press the reset button

Once your board is flashed, press the reset button (although this step is unnecessary as the board will auto reset). This app currently works with the OTA.h APIs and hasn't been tested with other implementations.

Ameba Cloud OTA library:

A recent addition to the Ameba library is the ability to do a cloud based (HTTP) OTA procedure.

This project needs a web server software running on your system or on the cloud. Some of the famous ones being:

• 1) nginx

• 2) apache tomcat

Once you have installed the web server just host your file in a directory structure in your web server. Note down the URL that will put against the file and keep it handy.

Generate OTA firmware

We generate OTA firmware to verify if the download from Web Server is complete.Open Arduino IDE and add a sketch file as below and print "Hello From Ameba!!" on the console every 1 second in the loop() function .

Copy ota.bin and put it to web Server htdocs (or the web server root) directory

• Generate checksum

Before remote OTA, we check ota.bin correctness via checksum. We can use the checksum tool provided by RTL8195 Github:

https://github.com/Ameba8195/Arduino/blob/master/ameba_tools_windows/tools/windows/checksum.exe

Generate the checksum

Open cmd and change to directory where you have the ota.bin file. Key in:

Checksum.exe ota.bin

203df9 is the checking code generated from checksum. Add a check.txt in the web server root (same place as the ota.bin file)

Install the OTA library:

The libraries we need are:

https://github.com/Ameba8195/Arduino/blob/master/libraries/AmebaCloudOTA.zip

Install the library in your sketches folder.

Burn the OTA firmware:

• Open “File” -> “Examples” -> “AmebaCloudOTA” -> “ota_cloud”, fill in AP SSID and Password. Remember to fill in Web Server IP Address and Port.

• Compile and upload to Ameba. Start downloading OTA from Web Server after pushing Reset button. And open the terminal.

• Check checksum after the download and start OTA. It restarts and prints ” Hello from Ameba!!!” if the process is successful.