Filter results by

General Update Procedure

You'll be following these steps for general application software (.deb) updates. Refer to the Package Signing article if you plan to send signed OTA packages.

  1. Preparation

  2. Create .deb packages

  3. Create updater script

  4. Create an OTA image using your Debian package

  5. Upload the package to ARTIK Cloud

  6. Trigger the update.

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

Prerequisites

To help you understand the process, we provide a "starter bundle" of prepared packages. You can use these to practice uploading to, and deploying from, ARTIK Cloud. If you want to use them, just follow the Procedure but substitute the starter bundle files instead of creating your own.

Download the starter bundle

Download a set of test packages for your gateway architecture, then unzip it and copy the files to your ARTIK root.

A710 gateway        A530 gateway

You should find:

  • test.tar.xz – contains test.deb as a typical package that you might create and install, along with updater.sh as a script that would execute the procedure.

  • sample.tar.xz and sample.tar.xz.signed – examples (both unsigned and signed) of an update to be performed.

Extract the files

Extract the contents of each package (we recommend choosing the unsigned one for your first run through).

            

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/

Obtain the latest phone app

Make sure you have Samsung ARTIK app revision 1.5.6 or later installed on your phone for this process to work correctly. Uninstall any existing prior version and then install the latest Android version from the Google Play store.

Preparation

The following steps are one-time preparation to make your system ready for OTA firmware update.

Prep 1. Upgrade gateway firmware

You must upgrade your gateway to at least os_18.05.00 as prior versions did not install the lwm2m-client service.

Prep 2. Create your own Device Type

You must create your own Device Type (not using a public one) in order to do OTA updates.

  1. Go to https://developer.artik.cloud/dashboard/

  2. Next to Device Types, select [+ NEW].

  3. Give your device a Device Display Name – what you want your users to see when they go to choose a new device.

  4. Give it a Unique Name – lower case, no spaces or punctuation aside from periods and underscores

  5. Optionally enter descriptive information, and hit Save Changes.

  6. On the screen now showing your created device, select [ . . . VIEW MORE DETAILS]

  7. Leave the window open so that you can copy the Device Type ID.

  8. Set your gateway ID to match your new Device ID in ARTIK Cloud.
    vi /usr/local/ble-onboarding/start-service.sh

    Copy and paste the Device Type ID of your newly created Device Type as indicated.

# Uncomment and put your own sdr dtid if needed
export SDR_DEVICE_TYPE_ID= < your own device type ID >
#export SDR_DEVICE_TYPE_ID=$(node sdr_get_dtid.js)

Prep 3. On-board the gateway

At least one device of your device type must be registered with ARTIK Cloud to enable Device Properties, so you'll need to on-board your gateway.

Delete any previous instance of the device on your phone and on ARTIK Cloud (for example, if you initially on-boarded your kit using the public Device Type). Then follow the on-boarding procedure for your gateway.

Afterwards, verify that the lwm2m-client service is running with the command:

systemctl status lwm2m-client

Prep 4. Activate the Device Type

Enable Device Properties for your device type in ARTIK Cloud by clicking the Device Management tab of the device type. Create and activate a manifest for it as well (even a single entry like Enabled is enough).

Prep 5. Configure how to deploy packages

You've got some settings to configure, all in the same launch script file. Edit this file as appropriate for your specific needs.

vi /usr/local/ble-onboarding/scripts/start_lwm2m_client.sh

Configure for signed or unsigned packages. You'll need to edit the LWM2M launch script according to whether you plan to incorporate signed packages.

export PACKAGE_TYPE="signed" for signed packages

export PACKAGE_TYPE="" for unsigned packages

Add certificate if not present. If you are using an older non-secure (not an "s" type) module, it may not have a required certificate for the OTA process. Check by running:

/usr/lib/aarch64-linux-gnu/artik-sdk/tests/security-test

If you are missing the Chain certificate, you'll see just a blank line:

artik_security_test:
. . .
TEST: test_security_get_certificate_and_key starting
Chain:
(just a blank line here?)
Certificate:
-----BEGIN CERTIFICATE-----
MIIChzCCAi2gAwIBAgIJAQAXBiEAAJ9XMAoGCCqGSM49BAMCMIGDMQswCQYDVQQG
EwJLUjEkMCIGA1UEChMbU2Ftc3VuZyBTZW1pY29uZHVjdG9yIEFSVElLMSYwJAYD
VQQLEx1BUlRJSyBIaWdoIFNlY3VyaXR5IERldmljZSBDQTEmMCQGA1UEAxMdQVJU
. . .

If so, then you'll need to add a certificate. First, edit the launch script as shown.

export ROOT_CA_PATH="/etc/artik_root.pem"

export SE_CERT_ID=""

Then, create a Chain certificate /etc/artik_root.pem with these contents.

1
2
3
4
5
6
7
8
9
10
11
12
13
-----BEGIN CERTIFICATE-----
MIICBzCCAa6gAwIBAgIQWULxj69HCVoOkJmX6zLgSzAKBggqhkjOPQQDAjBjMQsw
CQYDVQQGEwJLUjEkMCIGA1UEChMbU2Ftc3VuZyBTZW1pY29uZHVjdG9yIEFSVElL
MRYwFAYDVQQLEw1BUlRJSyBSb290IENBMRYwFAYDVQQDEw1BUlRJSyBSb290IENB
MCAXDTE3MDYxNTIwNDM1OVoYDzIwNjcwNjE1MjA0MzU5WjBjMQswCQYDVQQGEwJL
UjEkMCIGA1UEChMbU2Ftc3VuZyBTZW1pY29uZHVjdG9yIEFSVElLMRYwFAYDVQQL
Ew1BUlRJSyBSb290IENBMRYwFAYDVQQDEw1BUlRJSyBSb290IENBMFkwEwYHKoZI
zj0CAQYIKoZIzj0DAQcDQgAEMXHP576GyYS6P7SKSiHTVNmnoHsBRQUe/PTytK1W
9972fZeiJCwknJxnnUTH0kzVe2yNi+DmPnME2oL2zIDu/qNCMEAwDgYDVR0PAQH/
BAQDAgEGMB0GA1UdDgQWBBSi0+GxtetCghfueBp61CoWUr4UlzAPBgNVHRMBAf8E
BTADAQH/MAoGCCqGSM49BAMCA0cAMEQCIGuP4Hdn20Qe8JjRVrVFJRP6SlKdm8Tx
Oqg0CwqyldZMAiA9cfcrALT8YrnR4zeluoDB5jrJDWSYMzTFwm6+2idLnA==
-----END CERTIFICATE-----

Specify package name. You'll need to export your file package name for ease of reference. For our example using the name test, edit the launch script to add it as follows.

export PKG_NAME='test'

Procedure

You're now ready to build an update package and send it to ARTIK Cloud for deployment to your gateway.

Step 1: Create .deb packages

These are the steps to create a generic test.deb package for any Ubuntu platform; any other name could be used. You'll typically use your Linux virtual machine to create the package.

The starter bundle you downloaded includes an example test.deb file, so you can skip past this procedure if you're trying things out for the first time.

  1. Create holding directories for your package – a test directory and a DEBIAN subdirectory.

    mkdir test && mkdir test/DEBIAN

  2. Copy files into your package. You can copy the files/binaries/scripts into your package with the full paths on the destination file system.

    For example, to put a file in:

    • /usr/local/bin/
       » you put it in test/usr/local/bin/

    • root/
       » create a root directory under test/ and put your binaries and files there.

  3. Create a control file in the /test/DEBIAN directory. For example:

    package: test
    version: 0.2.1
    Maintainer: Kd
    Architecture: all
    Description: Test deb package

  4. Add a post-installation script. You can create a file postinst in the DEBIAN directory. Make sure it is executable. It will run when the installation is complete.

  5. Create the package.

    dpkg-deb --build test

    This creates a test.deb file.

You'll want to manually copy the package to your ARTIK board and install it locally to verify that it works as expected.

  • See a summary of what it contained in the package before installing it:
    dpkg -I test.deb

  • Install your package:
    dpkg -i test.deb

After installation, you can find all the files you put inside test/usr/local/bin or in /root

  • If you want to remove your package:

    dpkg -r test

    All binaries and files will be deleted from the target system.

Step 2: Create updater script

The updater script is responsible for installing updated packages and their dependencies in the proper order, and for returning an error in case of failure. To act on the gateway, it simply runs dpkg -i on specified .deb files in the OTA package.

Developers may optionally customize the updater script specifically for a particular OTA update, in addition to the required functionalities listed.

A simple updater.sh looks like this:

1
2
3
4
5
6
7
8
9
#!/bin/bash

dpkg -i *.deb
if [ $? -eq 0 ]; then
	exit 0;
else
	apt-get install -f -y --allow-downgrades
	exit $?
fi

The complete update file set also contains .deb files like this:

ota-sample-app_1.1-0_armhf.deb

Step 3: Create OTA image using your Debian package

Once you have assembled your set of files to be deployed as an update, you need to package them before uploading to ARTIK Cloud. This is quick – you just put all the files in a directory, create a .tar file from them, and then compress that to .xz format.

You can do this either with tar commands on your Linux system or using a program like 7-Zip directly from Windows.

        

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/ .

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.


Step 4: Upload the package to ARTIK Cloud

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.

In the upload window, use the browse button to select the prepared package to upload. Select Application as the image type. Finally, enter the version for the package; it must exactly match the one you set earlier in DEBIAN/test/control.

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.

Step 5: 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.

  • 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

  • Version of package. Check that you specified the right version when you uploaded the package to ARTIK Cloud here.

  • Package details. Check that you configured the package naming details as noted here.
    export PKG_NAME=(your package name)
    export PACKAGE_TYPE=(either "signed" or blank)

  • Root CA path and ID. Check your root CA path and ID. The default for ARTIK is shown.

    export ROOT_CA_PATH=""
    export SE_CERT_ID="artik"

    If you signed your package against your root CA, then you have to provide that root CA path and leave SE_CERT_ID blank.

    export ROOT_CA_PATH="<your_root_ca_path>"
    export SE_CERT_ID=""

  • Error logs. Monitor the logs during the OTA update process. It will show you everything for Gateway OTA, where it is downloading and what is the result or error. You can debug using this command to see the process.

    journalctl -f -u lwm2m-client

-- Logs begin at Mon 2018-06-18 20:41:02 UTC. --
Jun 18 20:41:04 artik start_lwm2m_client.sh[2308]: 90debaf1ee8c4b38a01eb9c3da1d8677 67e22aa9944c4f4e8874305aadf535ba non-sdr ota-sample-app /etc/artik_root.pem
Jun 18 20:41:09 artik start_lwm2m_client.sh[2308]: Launch lwm2m client
Jun 18 20:41:09 artik start_lwm2m_client.sh[2308]: start lwm2m connection
Jun 18 20:41:09 artik start_lwm2m_client.sh[2308]: Error running script Error: Command failed: /usr/local/ble-onboarding/scripts/get_package_version.sh ota-sample-app
Jun 18 20:41:09 artik start_lwm2m_client.sh[2308]: dpkg-query: no packages found matching ota-sample-app
Jun 18 20:41:14 artik start_lwm2m_client.sh[2308]: SSL verify ? 0
Jun 18 20:42:05 artik start_lwm2m_client.sh[2308]: [1B blob data]
Jun 18 20:42:05 artik start_lwm2m_client.sh[2308]: LWM2M changed: /5/0/1
Jun 18 20:42:05 artik start_lwm2m_client.sh[2308]: Downloading https://api.artik.cloud/v1.1/updates/urls/eb03ed45df644aea91295e65c5024668?tk=GmnZYeKSSB2wKTs5nDV4FP6O6qrEciN4A2AxKVwNxOK9Or8QJFvPPyebeNBuAYfKwlYuPCLcL1i41qjOZqqPWsAB%2FybCHd%2FMhn6xizuDGA4%3D
Jun 18 20:42:07 artik start_lwm2m_client.sh[2308]: Download successful
Jun 18 20:42:07 artik start_lwm2m_client.sh[2308]: OTA package needs to be signed. Verifying...
Jun 18 20:42:07 artik start_lwm2m_client.sh[2308]: Start pkcs7VerifySignature
Jun 18 20:42:15 artik start_lwm2m_client.sh[2308]: {"error":false,"reason":"Verification successful","error_code":0,"signing_time":"2018-06-18T20:38:00.000Z"}
Jun 18 20:42:15 artik start_lwm2m_client.sh[2308]: tar -xvf /root/ota-update/firmware.tar.xz -C /root/ota-update/
Jun 18 20:42:15 artik start_lwm2m_client.sh[2308]: OTA File decompressed
Jun 18 20:42:40 artik start_lwm2m_client.sh[2308]: [1B blob data]
Jun 18 20:42:40 artik start_lwm2m_client.sh[2308]: LWM2M execute: /5/0/2
Jun 18 20:42:40 artik start_lwm2m_client.sh[2308]: Command FIRMWARE UPDATE received.
Jun 18 20:42:40 artik start_lwm2m_client.sh[2308]: Update successful
Jun 18 20:42:41 artik start_lwm2m_client.sh[2308]: ota-sample-app 1.0-0
Last updated on: