Cloud FOTA Cloud FOTA Updates Table of Contents Introduction Prerequisites Upgrade from AWS S3 Bucket Setup S3 Bucket Get S3 HTTPS Endpoint Upgrade from AWS EC2 using NGINX Setup EC2 Instance Install and Prepare NGINX Trigger Cloud FOTA Upgrade Pinnacle 100 and MG100 App Only HL7800 Cellular Modem Only Introduction Cloud FOTA updates to the Pinnacle 100/MG100/BL5340 require, at a minimum, a webserver that can serve up a static webpage containing the *.bin upgrade file (NOTE: Devices request this file using partial content HTTPS requests to the static webpage). The relevant code to include this functionality in your own project is located in the _/ble_gateway_firmware/app/http_fota_ folder when you clone the [Pinnacle 100 Firmware Manifest](https://github.com/LairdCP/Pinnacle-100-Firmware-Manifest) or in the _/BLE_Gateway_Firmware/app/http_fota_ folder when you clone the [BL5340 Manifest](https://github.com/LairdCP/BL5340_Firmware_Manifest). The following discusses how to perform the upgrade two ways, using an Amazon Web Services (AWS) S3 Bucket and using an NGINX webserver running on an AWS EC2 instance. NOTE: If you are currently running the OOB Demo Firmware and connected to Ezurio’s Bluegrass Demo site, and the desire is to upgrade the OOB Demo Firmware to a newer version, use the instructions here WARNING: The Nordic Download Client used to facilitate the HTTPS FOTA Upgrade limits the size of the Download Host DNS and Download File names, the default sizes are as follows: DOWNLOAD_CLIENT_MAX_FILENAME_SIZE(=192) "Maximum filename length (stack)" DOWNLOAD_CLIENT_MAX_HOSTNAME_SIZE(=64) "Maximum hostname length (stack)" Prerequisites Pinnacle 100/MG100/BL5340 that supports Cloud HTTP FOTA upgrades, this would include any unit running the OOB Demo v4.0 or above and any custom firmware implementation that includes the Cloud HTTP FOTA functionality *.bin file for the Firmware you want to load, desired revision must be different than current revision on Pinnacle 100/MG100/BL5340 Official releases available here for the Pinnacle 100/MG100 480-00052 for Pinnacle 100 Modem 480-00070 for MG100 Gateway Official releases available here for the BL5340 480-00115 for the BL5340 development kit Custom FW builds use app_update.bin which is located in the build directory <project_folder>/ble_gateway_firmware/build/<project>/zephyr/app_update.bin (for Pinnacle 100/MG100) or <project_folder>/BLE_Gateway_Firmware/build/<project>/zephyr/app_update.bin (for BL5340) HTTP or HTTPS endpoint serving a static webpage containing the *.bin upgrade file, e.g. http://pinnacle100.com/<bin_filename>.bin WARNING: To use HTTPS, the file must be served from an AWS S3 bucket. There is no support for using a custom HTTPS server at this time. Ability to publish an MQTT message to the Pinnacle 100 or MG100, this could be: Pinnacle 100/MG100/BL5340 running the OOB Demo and connected as a Thing through IoT Core in AWS, See here for instructions Pinnacle 100/MG100/BL5340 running custom firmware that includes the Cloud HTTP FOTA and MQTT functionality, used with an MQTT broker like Mosquitto Upgrade from AWS S3 Bucket Setup S3 Bucket In your AWS account, make a new S3 bucket and give it the following permissions: { "Version": "2012-10-17", "Id": "Policy1619206380275", "Statement": [ { "Sid": "Stmt1619206371073", "Effect": "Allow", "Principal": "*", "Action": "s3:GetObject", "Resource": "arn:aws:s3:::pinnacle100/*" } ] } Make sure that the bucket is publicly available by turning OFF Block Public Access: Turning off Public Access Select Upload and drag-and-drop or select Add Files to add your *.bin file to your S3 bucket Get S3 HTTPS Endpoint Navigate to the location of the *.bin file in the S3 Bucket Select the *.bin file by clicking the file or checking the box next to the filename Select Copy URL NOTE: The URL should look similar to this: https://pinnacle100.s3-us-west-2.amazonaws.com/<filename>.bin Save this address to be used in the Trigger Cloud FOTA Upgrade section SKIP TO Trigger Cloud FOTA Upgrade SECTION Upgrade from AWS EC2 using NGINX Setup EC2 Instance Launch a new EC2 Instance Choose AMI: Ubuntu 20.04 was used for this testing Choose Instance Type: t2.micro instance is sufficient Keep defaults for Configure Instance, Add Storage, and Add Tags Configure Security Group: Select Add Rule and select HTTPS and optionally HTTP Select Review and Launch Select to use an existing Key Pair, if you have one and have access to it, or generate a new one (NOTE: Be sure to save this in a folder that isn’t publicly accessible and is Read-Only) Wait for the EC2 Instance to enter the Running state and note its Public IPv4 DNS Follow instructions here to connect to your EC2 Instance Run the following commands to update your EC2 Instance sudo apt update sudo apt upgrade Install and Prepare NGINX Install NGINX on your EC2 Instance using the following command: sudo apt install nginx Navigate to the /var/www/ directory and modify the permissions for the /html folder by issuing the following: ~$ cd .. /home$ cd .. /$ cd var/www /var/www$ sudo chmod 777 ./html Use Secure Copy (scp or pscp) to copy the *.bin file into the /var/www/html/ directory Trigger Cloud FOTA Upgrade To start a firmware update, publish an MQTT message to the device update topic for the Pinnacle 100/MG100/BL5340 (e.g. $aws/things/deviceId-<id>/shadow/update). Do not attempt to do both modem and app firmware at the same time. Pinnacle 100/MG100/BL5340 App Only Replace the values under “app” with those that correspond to your update. If you use a folder structure in your S3 Bucket or NGINX Server, be sure to note that in the downloadFile entry (e.g. fw/480-00052-R4.0.0.1614788169_LTE-M_FOTA.bin). NOTE 1: If using an S3 Bucket as the host, only copy in the piece up to and including the ‘.com’ to downloadHost , the remaining bit (file location) gets copied into downloadFile (excluding the leading ’/’) NOTE 2: The Pinnacle 100/MG100/BL5340 will request the download using a Partial Content Header and defaults to 2KB chunks with each request. To change the size of these chunks see information here { "state": { "desired": { "app": { "desired": "4.0.0", "downloadHost": "https://<S3_Bucket_HTTPS_or_Public_IPv4_DNS_for_EC2>.com", "downloadFile": "480-00052-R4.0.0.1614788169_LTE-M_FOTA.bin", "start": 1611172151, "switchover": 1611172151 } } } } The desired firmware version must be different from the running firmware version to kick off the update. start is the time used to schedule when to download the update. If time is in the past, it will begin immediately. switchover is the time used to schedule when to install the update. If time is in the past, it will begin immediately. HL7800 Cellular Modem Only (Pinnacle 100/MG100 only) IMPORTANT NOTE: Contact Ezurio technical support to obtain an official modem update. Flashing in an unsupported version may cause your device to malfunction. To update the hl7800, replace the values under “hl7800” with those that correspond to your update. { "state": { "desired": { "hl7800": { "desired": "4.4.14.99", "downloadHost": "https://<Laird_Connectivity_Server_Address>.com", "downloadFile": "Sentrius-MG100/hl7800/4.4.14.99/4.4.14.0_4.4.14.99.bin", "downloadedFilename": "4.4.14.0_4.4.14.99.bin", "hash": "8752ce900ced895d548f8dafc0740270dc6a9bc4ee512cbd46f08aeefae04944", "start": 0, "switchover": 0 } } } } The hash value is only used to validate the integrity of the downloaded modem images. The hash value is a sha256 hash. BL5340 Upgrade Note Note that at present on the BL5340, only application-core FOTA updates are available, it is not currently possible to FOTA update the network-core application.
