Filter results by

General Update Procedure

ARTIK 030 devices using the IoTivity framework with Thread technology get their updates by way of the Edge Node Manager running in the gateway.

Prerequisites

You'll want to begin from a known-working starting point.

This latter step serves mainly to give you the conceptual knowledge of the process. Once it's working, delete this on-boarded device from your phone and from ARTIK Cloud. You'll create your own device to on-board and eventually update its firmware over-the-air (OTA).

Operational Overview

The way the system handles update of edge node firmware is straightforward. Here's an overview of the flow; follow along on the diagram.

  1. Using the ARTIK Cloud developer site, you need only load the package to be transferred and trigger the update.

  2. ARTIK Cloud sends the URI of that package to the gateway.

The next steps are all carried out by the Edge Node Manager, running on the gateway.

  1. Requests and carries out transfer of the package identified by that URI.
  2. Verifies that the package has not been tampered with.
  3. Extracts package contents:
    -- updater-app tool (executable file)
    -- updater.sh (script file)
    -- package.json (manifest file)
    -- ARTIK_Thread_OTA_server (driver file)
    -- the update image itself (.ebl file).
  4. Runs the script and executes its instructions, ultimately running updater-app

The final steps perform the update.

  1. updater-app communicates with the intended target to copy over the new image, by way of the driver (gateway side) and a plugin (edge node side).
  2. The plugin takes the steps noted in the diagram to activate the update, then returns status to ENM.
  3. ENM returns the status of the operation to ARTIK Cloud.

OTA update is available on all levels of ARTIK Cloud service – an Enterprise account is not required.

OTA Package Contents

ENM expects an OTA upgrade packaged in a particular format depending upon the target device type. You construct this package and then load it to ARTIK Cloud for deployment.

ARTIK 030 OTA packages must contain:

  • An updater-app executable that orchestrates update operations from the gateway
  • A script updater.sh that is user-modified to handle any preparatory activities; it calls updater-app as well as other programs you define
  • A gateway-side driver ARTIK_Thread_OTA_server that interacts with an Edge Node Client plugin; pushes the firmware to the Edge device over Thread
  • A (a local list, not the same as the ARTIK Cloud manifest)
    package.json
    { 
      "application": "< application name >"
      "version": "< version of the new firmware >"
      "filename": "< name of the firmware .ebl file to flash >"
      "sha256sum": "< SHA256 sum of the firmware .ebl file >",
      "packet_size" : < Size of each chunk (bytes): 1024 >,
      "retry_count" : < Packet retry count : 5 >,
      "ack_timeout" : < Packet ack timeout (seconds) :5 >,
      "max_ota_attempts" : < Maximum OTA attempts : 5 >,
      "ota_retry_wait_period" : < Waiting time between successive 
    OTA attempts (seconds): 60 > }
  • The .ebl file containing the new firmware to flash.

We provide starter package software bundles containing all of these files. You can try them out to get a feel for the operation, and then modify them for your own application.

Updater. The updater.sh script calls the provided updater-app tool, which:

  1. Checks that the version in the manifest is higher than the current version passed as an environment variable

  2. Computes the SHA256 sum of the downloaded file and compares it with the one provided in the JSON manifest

  3. Transfers the new .ebl file to the edge node device via the driver and plugin

  4. Triggers the firmware update, waits for the plugin to indicate completion, and retrieves the result.

The script returns the update result to ARTIK Cloud.

Incorporating Edge Node Client

An ARTIK OTA plugin is required on the Edge device to handle the OTA update request from the Updater and driver. It's known as the Edge Node Client (ENC). You'll need to upgrade your Simplicity Studio tool to build this plugin into your edge node firmware. It requires the IAR compiler to be installed.

Both the existing edge node firmware image, as well as the new image to be Flash-loaded, must have been compiled with the correct OTA plugin.

Provision A030 Edge Node Client

The ARTIK custom OTA plugin for the Silicon Labs Thread stack is responsible for:

  • Receiving image packets over CoAP
  • Flashing them to the external flash memory device
  • Validating the complete image
  • Triggering a bootloader to load the image into internal flash memory.

You'll need to incorporate this custom plugin within your development flow.

  1. Prepare your development system by following this procedure.

    Upgrade Simplicity Thread stack for ARTIK OTA

    Your Simplicity Studio installation requires not only the Silicon Labs Thread stack, but also a custom ARTIK overlay that allows integration of the Edge Node Client in A030 firmware you build. The overlay is provided in a compressed file.

    Install the A030 OTA Edge Node Client in the Silicon Labs Thread 2.5.0.0 stack.

    1. Download and unzip the overlay folders package.

      silabs-thread-v2.5.0.0-artik-3.1.4.zip

    2. Launch Simplicity Studio and connect the ARTIK 030 Development Kit to the development machine using a USB cable. Make sure the switch is set to AEM.

    3. In Simplicity Studio, sign into your Silicon Labs account. After you are logged in, click Update Software (the down-arrow icon).

    4. You'll be using the Package Manager. In the Product Updates tab, click on Update All to install all available updates. You may be requested to restart Simplicity Studio.

    5. Select the SDKs tab, set Version to All (by default only the latest is shown), and install the Thread SDK - 2.5.0.0 package (this may be older than your current Thread). Close Package Manager.

    6. Under Window » Preferences, expand Simplicity Studio and click on SDKs. Make sure the needed Thread stack is checked. Then click on this entry to highlight it and show the file path (under Location:).

    7. Copy this path and use it to open an explorer window, then close Simplicity.

    8. From the unzipped software package, copy the folders and their contents to the new window, overlaying the existing folders. Permit overwriting when asked.

    9. Restart Simplicity Studio. The changes in the stacks should now be in effect.
    10. Go to Launch view. If your A030 board is connected, it now appears in “Devices”. click the [+] on the J-Link adapter, then click the ARTIK 030 Mesh entry to get board-specific documentation and software listings.

  2. Build an image, and initialize your A030 board with it, by following this procedure.

    Make A030 firmware OTA-update-ready

    With Thread and the plugin files installed on your development PC, you can build OTA-update-capable A030 firmware.

    Step 1. Create the “ARTIK Edge Node” Simplicity project. Follow the same procedure as for a ZigBee project, but choose as shown.

    Silicon Labs Thread as the application type
    Thread 2.5.0.0 as the stack
    ARTIK Edge Node as the application
    BRD4300D as the board

    IAR ARM as the compiler

    Step 2. Generate the files.

    Step 3. Create your Device Type in ARTIK Cloud and add its dtid into the A030 edge node code.

    1. Create your Device Type, create and activate the manifest (even a single entry like Enabled is enough), and enable Device Properties.

    2. Find its dtid and copy it.

    3. Go to the iotivity-token.h file and edit the DEFAULT_AKCDTID value, replacing it with your ARTIK Cloud Device ID dtid.

    4. Build the code to incorporate the change.

    Step 4. Obtain a image, then flash the main and bootloader .s37 images to the A030 device. Your board now contains the proper OTA-enabled firmware to receive a remote firmware update.

    • Build the correct Thread bootloader to match the code release. Follow the bootloader procedure in the ZigBee article, this time choosing the "gecko_sdk_suite" v2.1 (same as the SDK Suite version from Step 1).

    • OR

    • Copy a pre-built bootloader from this location.
      C:\SiliconLabs\SimplicityStudio\v4\developer\sdks\gecko_sdk_suite\v2.1\protocol\thread_2.5\tool\bootloader-efr32mg1p132f256gm48-brd4300d\app-bootloader-spiflash

    Step 5. Commission and on-board the A030 device. (If you previously did the Connect to the World exercise, make sure you delete your instance from the phone app and ARTIK Cloud before attempting to commission and on-board again as a new Device Type.)

    You should now be able to see your device type on https://my.artik.cloud/devices and can use the Device Management tab to upload an OTA firmware image to update the A030 device at any time.

Creating Update Packages

It is easiest to create an OTA update package by starting from a reference package. While the update package can be prepared in any Linux environment, you may want to do it on an ARTIK 530/710 board so that you can "try out" the package components locally before deploying to ARTIK Cloud.

Extract starter package

  1. From the correct software bundle for your gateway that you downloaded and unzipped here, locate the tar.xz files. There are two: an original and an "updated" version, so that you can start with one and later update to the other.

  2. Extract the contents of a package (choose the non-updated one to start).

                

Extract the package using 7-Zip

  1. Copy your download to C:\Temp or another folder.

  2. Browse to this folder in Explorer and right-click on the file to extract.
    – Click 7-Zip
    – Click Extract Here

  3. Right click on the newly created .tar file to extract.
    – Click 7-Zip
    – Click Extract to …

  4. Browse to the newly created directory. It contains all the files that were contained in the archive.

Extract the package using Linux

  1. Copy the downloaded file package to a directory on your Linux development system.
  2. Create an output directory to hold the initial package contents.
    mkdir output
  3. Uncompress the standard file package to your created directory.
    tar -xvf _package.tar.xz -C output/

Build an Edge Node OTA update package

The starter directories already contain updater-app, updater.sh, driver, and package.json files.

  1. Create your updated ARTIK 030 firmware binary in Simplicity Studio, starting from an ARTIK Edge Node project using the appropriate ARTIK OTA plugin.

  2. Copy the image file into the appropriate directory, and delete any files that will not be needed. You'll use the .ebl format version of the Silicon Labs project image.

  3. Edit the updater.sh and package.json files as needed for your application, paying close attention to the version number in the manifest.

Assemble the archive

The last thing required is to compress the new group of files.

        

Repackage the archive using 7-Zip

  1. In the File Explorer, select all the files you want to archive, right-click the selection, click 7-Zip then Add to archive

  2. In the 7-Zip window, make sure to select tar as Archive format, change the filename of the archive as you see fit, then click OK. It will generate the new .tar file.

  3. Right-click on this new file then choose 7-Zip and Add to archive…

  4. In the 7-Zip window, choose xz as the Archive format, change the filename if needed then click OK.

The new package with your modified content has been generated.

Repackage the archive using Linux

From your output/ directory, compress the files.

tar -cJf package.tar.xz -C output/ .

Deploying ARTIK Cloud Update

The final steps will be to sign your package if desired, upload it to ARTIK Cloud, and trigger deployment.

Sign the package if needed

Unsigned packages. If you are not signing your package, the .xz file is the one to upload to ARTIK Cloud for deployment.

Signed Packages. If you will be using a signed package, sign the .xz file now:

  • Make a copy of the file and call it package.tar.xz

  • Jump to Package Signing and sign the file

  • Return here to continue.

package.tar.xz.signed will be the output. Rename the package part to its original name and version before you upload it to ARTIK Cloud.

This package cannot be opened as a tar.xz in its current form, as it has a prepended signature.


Upload the package to ARTIK Cloud

  1. In the ARTIK Cloud developer portal, go to the Device Management tab of your Device Type, click the OTA Updates subtab, then click the Upload new image button.

  2. In the upload window, use the browse button to select the prepared package to upload. Select Edge Node as the image type. Finally, enter the version for the package; it must exactly match the one you set in the JSON manifest.

  3. Click the Upload button to finalize the uploading. Note that after uploading a package, it is impossible to delete it from the ARTIK Cloud portal.

Trigger the update

  1. Go to the ARTIK Cloud developer portal, and browse to the Device Management pane for that device type. In the devices list, identify the currently connected board by its device ID.

  2. Check the device (or devices) you want to update, click Execute then OTA update.

  3. Select the package you want to use for update, then click Next.

  4. In the final window, you can select a date to schedule the update, or leave empty to launch the update right now. Click Perform OTA Update when ready.

To follow the update process from the ARTIK Cloud portal, go to the Tasks subtab under the Device Management pane. Identify the OTA update task from the list then click it to get the details.

On the device side, it should download the OTA package and then flash the new firmware and follow whatever other script instructions were included.

You can check the device log to see whether the new firmware has been properly booted by looking at the new version string. On the ARTIK Cloud portal side, the task status will be updated after a bit (usually a couple of minutes) to reflect the success of the OTA update.


Troubleshooting

Having problems? Review these topics to determine what went wrong.

General checks

  • Network connection. You should see both the IPv4 address of wlan0 and the tunneled IPv6 addresses tun0 of the border router. For example:
    [root@artik ~]# hostname -I
    10.0.1.122 2001:db8:385:9318:5064:c369:c2ed:9f08 fd39:43d9:a28c:0:4f9f:9b2f:9783:59dc

  • Internet access. Ping a known-accessible site to make sure you have Internet access.
    [root@artik ~]# ping 8.8.8.8
    PING 8.8.8.8 (8.8.8.8) 56(84) bytes of data.
    64 bytes from 8.8.8.8: icmp_seq=1 ttl=120 time=12.6 ms
    64 bytes from 8.8.8.8: icmp_seq=2 ttl=120 time=29.9 ms
    64 bytes from 8.8.8.8: icmp_seq=3 ttl=120 time=56.9 ms

  • Thread Network. Check that your A030 end devices are in the Thread network. Check status on your ARTIK Cloud device managemant portal; they should be shown as 'Active'.

  • Check that the enmd is running on the Gateway.

    systemctl status enmd

  • Check the ENM logs on the Gateway, It will be easy to debug the problem If there are any errors related to 030 OTA.

    journalctl -f -u enmd

    Click to see a sample data log with highlighted points to check.

-- Logs begin at Tue 2018-06-19 20:20:10 UTC. --

Jun 19 22:44:00 artik enmd[2510]:  LWM2M client [Lwm2mClient-d2dd0fd8-6764-418f-9a29-000b57366fe0]: Firmware URL [https://api.artik.cloud/v1.1/updates/urls/eb88e711b70d4aab8e34761f6972c075?tk=W4ZsqbdyT%2Ftn%2FF4Dk%2BXyyW6uVoy5%2BighkGGCfRV1bgcrQTSivSQw1JwyQjr%2FAVZiLGnLC%2BE4P5yPI6bKMdGa7f6TD2PUF3a7ln6ZFzLUvy8%3D] received for node d2dd0fd8-6764-418f-9a29-000b57366fe0
Jun 19 22:44:00 artik enmd[2510]: 2018-06-19 22:44:00,119 INFO  [default] Lwm2m client [ Lwm2mClient-d2dd0fd8-6764-418f-9a29-000b57366fe0 ]: Update node firmware udpate state to  1
Jun 19 22:44:02 artik enmd[2510]: 2018-06-19 22:44:02,276 INFO  [default] Lwm2m client [ Lwm2mClient-d2dd0fd8-6764-418f-9a29-000b57366fe0 ]: Update node firmware udpate state to  2
Jun 19 22:44:02 artik enmd[2510]:  LWM2M client [Lwm2mClient-d2dd0fd8-6764-418f-9a29-000b57366fe0]: Firmware Downloaded at /tmp/update-d2dd0fd8-6764-418f-9a29-000b57366fe0
Jun 19 22:44:04 artik enmd[2510]:  LWM2M client [Lwm2mClient-d2dd0fd8-6764-418f-9a29-000b57366fe0]: FIRMWARE UPDATE command received for node d2dd0fd8-6764-418f-9a29-000b57366fe0
Jun 19 22:44:04 artik enmd[2510]: 2018-06-19 22:44:04,496 INFO  [default] Lwm2m client [ Lwm2mClient-d2dd0fd8-6764-418f-9a29-000b57366fe0 ]: Update node firmware udpate state to  3
Jun 19 22:44:05 artik enmd[2510]: 2018-06-19 22:44:05,499 INFO  [EdgeNodeManager] [ d2dd0fd8-6764-418f-9a29-000b57366fe0 ] is  Updating
Jun 19 22:44:05 artik enmd[2510]: 2018-06-19 22:44:05,575 INFO  [EdgeNode-3202] Upgrade firmware of device  d2dd0fd8-6764-418f-9a29-000b57366fe0
Jun 19 22:44:05 artik enmd[2510]: 2018-06-19 22:44:05,576 INFO  [EdgeNode-3202] Executing command [ cd /tmp/update-d2dd0fd8-6764-418f-9a29-000b57366fe0 ; DEVICE_INFO=/tmp/update-d2dd0fd8-6764-418f-9a29-000b57366fe0/device.json /bin/sh  /tmp/update-d2dd0fd8-6764-418f-9a29-000b57366fe0/updater.sh ]
Jun 19 22:44:05 artik enmd[2510]: File is /tmp/update-d2dd0fd8-6764-418f-9a29-000b57366fe0/device.json
Jun 19 22:44:05 artik enmd[2510]: Firmware is artik-edge-node.ebl
Jun 19 22:44:05 artik enmd[2510]: SHA256 computed on firmware file is 129e64dc72e971324ea7a08f3cdbaffbb2cab2a4d0923289d04f90832d074525
Jun 19 22:44:05 artik enmd[2510]: Waiting to acquire lock TRY COUNT 1
Jun 19 22:44:05 artik enmd[2510]: Packet cool off period.Waiting before starting.
Jun 19 22:45:05 artik enmd[2510]: Lock acquired for node d2dd0fd8-6764-418f-9a29-000b57366fe0 TRY COUNT  1
Jun 19 22:45:05 artik enmd[2510]: Device IP Address is fd62:1f35:3b26:0:ea32:35a7:cd5d:d1d0
Jun 19 22:45:05 artik enmd[2510]: launching command [./ARTIK_Thread_OTA_server -f artik-edge-node.ebl -a  fd62:1f35:3b26:0:ea32:35a7:cd5d:d1d0 -p 1024 -r 5 -t 5 > firmwareupdate.log]
Jun 19 22:48:31 artik enmd[2510]: Lock released
Jun 19 22:48:35 artik enmd[2510]: 2018-06-19 22:48:35,798 INFO  [EdgeNode-3202] Firmware system command result  0
Jun 19 22:48:35 artik enmd[2510]: 2018-06-19 22:48:35,799 INFO  [EdgeNode-3202] Firmware Update Result for Node  d2dd0fd8-6764-418f-9a29-000b57366fe0  is   true
Jun 19 22:48:35 artik enmd[2510]: 2018-06-19 22:48:35,799 INFO  [EdgeNodeManager] [ d2dd0fd8-6764-418f-9a29-000b57366fe0 ] is  Online
Jun 19 22:48:35 artik enmd[2510]: 2018-06-19 22:48:35,871 INFO  [EdgeNode-3202] NODE :  d2dd0fd8-6764-418f-9a29-000b57366fe0  state : Online
Jun 19 22:49:05 artik enmd[2510]: 2018-06-19 22:49:05,937 INFO  [default] Lwm2m client [ Lwm2mClient-d2dd0fd8-6764-418f-9a29-000b57366fe0 ]: Updated resource IP Address to   fd62:1f35:3b26:0:ea32:35a7:cd5d:d1d0
Jun 19 22:49:05 artik enmd[2510]: 2018-06-19 22:49:05,937 INFO  [default] Lwm2m [ Lwm2mClient-d2dd0fd8-6764-418f-9a29-000b57366fe0 ]: Update resource firmware version to   3.1.4

Jun 19 22:50:36 artik enmd[2510]: 2018-06-19 22:50:36,054 INFO  [default] Lwm2m client [ Lwm2mClient-d2dd0fd8-6764-418f-9a29-000b57366fe0 ]: Updated resource IP Address to   fd62:1f35:3b26:0:ea32:35a7:cd5d:d1d0
Jun 19 22:50:36 artik enmd[2510]: 2018-06-19 22:50:36,055 INFO  [default] Lwm2m [ Lwm2mClient-d2dd0fd8-6764-418f-9a29-000b57366fe0 ]: Update resource firmware version to   3.1.4
Jun 19 22:50:36 artik enmd[2510]: 2018-06-19 22:50:36,055 INFO  [default] Lwm2m client [ Lwm2mClient-d2dd0fd8-6764-418f-9a29-000b57366fe0 ]: Update node firmware udpate result  1
Jun 19 22:50:36 artik enmd[2510]: 2018-06-19 22:50:36,055 INFO  [default] Lwm2m client [ Lwm2mClient-d2dd0fd8-6764-418f-9a29-000b57366fe0 ]: Update node firmware udpate state to  0

ENM configuration failure

If you are seeing failures, use the ENM REST APT to check the configuration. In the examples shown below, replace the IP of 10.0.1.95 with your own gateway IP address.

Command

curl -k --digest -uadmin:admin -X GET -H "Content-type: application/json" "https://10.0.1.95/v1.0/service/conf"

Response

{"AKCApi":1,"DbusApi":0,"Debug":0,"DefaultConfiguration":{"currency":" ","deviceName":"Edge Node Manager","devicename":"",
"location":"","locationName":","locationname":"","region":"},"EventApi":1,"Lwm2mApi":1,"RestApi":1,"akcEnableWebsockets":1,"client_id":"","cloudDeviceTypeId":{"ARTIK-030":"","ARTIK-050_EVK":""},"dbPath":"/var/local/enmd.db","deviceOfflineTimeoutInterval":120,"discoveryEnableOnStartup":1,"lwm2m_client_lifetime":120,"lwm2m_server_address":"coaps+tcp://coaps-api.artik.cloud:5689","maxEventDBSize":10240000,"network":{"connectionTimeout":10000,"monitorInterface":"wlan0","testEndpoint":"https://api.artik.cloud"},"notifyEventDBSpace":10,"pingInterval":30,"platformConfiguration":{"otaApplicationName":"enmd","otaRootCA":"artik","otaSignatureVerification":false},"proxy":{"http_proxy":"","https_proxy":""},"resinApplicationId":{"ARTIK-030":"","ARTIK-050_EVK":""},"scan_period":10,"storeAndForward":{"clearStrategy":"NONE","delayUploadInterval":3600,"enable":false,"maxDBStorageSize":1024000,"maxTTL":7200,"useOriginalTimeStamp":true},"token":"15f15ae64ec7468c8f8a7e5768b28efd","user_id":"a961221c464e4823b1a621e03db85cbd","webPort":443}

If you are doing signed OTA then update the configuration using these commands.

curl --digest -k -uadmin:admin -X PUT -H "Content-Type: application/json" -d'{"platformConfiguration" : {"otaSignatureVerification" : true}}' "https://10.0.1.95/v1.0/service/conf"

In the second command, provide the path of your CA.

curl --digest -k -uadmin:admin -X PUT -H "Content-Type: application/json" -d'{"platformConfiguration" : {"otaRootCA" : "/etc/artik_root.pem"}}' "https://10.0.1.95/v1.0/service/conf"

Last updated on: