Introduction: Programming Arduino Over the Air (OTA) - Ameba Arduino
There are many Wi-Fi microcontroller out there in the market, many makers enjoy programming their Wi-Fi microcontroller using Arduino IDE. However, one of the coolest features that a Wi-Fi microcontroller has to offer tend to be overlooked, that is programming and uploading your code remotely and wirelessly using OTA (Over-The-Air) function.
In this Instructable, I will show you how to set up OTA on your Wi-Fi microcontroller using ubiquitous Arduino IDE on Ameba Arduino Wi-Fi microcontroller!
Supplies
- Ameba Arduino x 1
Step 1: OTA
OTA(Over-The-Air) refers to the online upgrade mechanism via Internet.
Arduino IDE offers OTA feature, which follows the workflow in the figure above.
(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.
Step 2: 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 above, 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 prceeds 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.
Apart from the code, there are some data blocks:
- System Data：
System data block starts from 0x00009000. There are two OTA-related data:
1. OTA address：4 bytes data starting from 0x00009000. It tells the OTA Image address. If the OTA address value is invalid (i.e., 0xFFFFFFFF), the OTA image in flash memory cannot be loaded correctly.
2. Recovery Pin：4 bytes data starting from 0x00009008, The recovery pin is used to determine which image (default Image 2 or OTA Image) to execute when both image is valid. If the recovery pin value is invalid (i.e., 0xFFFFFFFF), the new image will be executed by default.
System data will be removed when we upload program to Ameba via DAP. That is, the OTA address will be removed and Ameba will determine there is no OTA image.
- Calibration Data：The peripheral calibration data is placed in this block. Normally these data should not be deleted.
Step 3: Boot Flow
From the image above,
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.
Step 4: Example
To use OTA feature, please upgrade DAP firmware to version > 0.7 (v0.7 is not included). The factory default DAP firmware is version 0.7. Please follow the instruction to upgrade DAP firmware: https://www.amebaiot.com/change-dap-firmware/
Open the example: "File" -> "Examples" -> "AmebaOTA" -> "ota_basic"
Fill in the ssid and password information in the sample code for network connection.
There are some parameters related to OTA:
§ MY_VERSION_NUMBER：In first version, we need to set OTA address and recovery pin. Since this time we upload via USB is the first version, we don't need to change this value.
§ OTA_PORT：Arduino IDE will find Ameba via mDNS. Ameba will tell Arduino IDE that it opens TCP port 5000 to wait for OTA image.
§ RECOVERY_PIN：Configure the pin used for recovery. We use pin 18 here.
Then we use USB upload program to Ameba. Click Tools -> Ports, check
the serial port to use：
Please note that Arduino IDE uses one port for upload program and output
log. To avoid the situation that the log cannot be output when we use OTA, we use other serial port terminal (e.g., Tera term or putty) instead of serial monitor to watch log message.
Then click upload and press reset button.
In the log message:
1. Between “===== Enter Image 1====” and “Enter Image 2 ====”, you can find “Flash Image 2:Addr 0xb000”. This means Ameba determines to boot from Default Image 2 at 0xb000.
2. After “Enter Image 2 ====”, you can find “This is version 1”. This is the log message we add in sketch.
3. After Ameba is connected to AP and gets IP address “192.168.1.238”, it activates mDNS and waits for client.
Next, we modify "MY_VERSION_NUMBER" to 2.
Click "Tools" -> "Port", you can see a list of
"Network ports". Find "MyAmeba at 192.168.1.238 (Ameba RTL8195A)", MyAmeba is the mDNS device name we set in sample code, and "192.168.1.238" is the IP of Ameba.
If you cannot find the network
port of Ameba, please confirm:
- whether your computer and Ameba are in the same local network?
- try to restart Arduino IDE.
- check log message in Serial Monitor to see whether Ameba is connected to AP successfully.
Then click upload. This time the program will be uploaded via TCP. In the log terminal, you can see client connection information.
When OTA image is downloaded successfully, Ameba will reboot and
following log will be shown in log terminal.
- Between “===== Enter Image 1====” and “Enter Image 2 ====”, you can see a log message “Flash Image 2:Addr 0x80000”. This means Ameba determines to boot from OTA Image at 0x80000.
- After “Enter Image 2 ====”, the log “This is version 2” is the message we add in sketch.
To recover to previous image after OTA image is downloaded to Ameba,
please connect the recover pin we set in sketch (i.e., pin 18) to HIGH (3.3V), and press reset.
Then Default image 2 will be
chosen when booting. Note that the downloaded OTA image is not deleted, once the recovery pin is disconnected from HIGH, the OTA image will be executed.
We summary the development flow using OTA in the following figure.
