Filter results by

On-Boarding

ARTIK Wi-Fi-equipped modules (A530/710 gateways or A05X edge nodes) can readily be "on-boarded" – connected to and registered with ARTIK cloud services. By way of an already on-boarded gateway, ARTIK Thread modules (A030) can also be on-boarded.

Linux-based On-Boarding

ARTIK gateway images os_18.05.00 and later come pre-configured with the ble-onboarding and lwm2m-client packages. These Linux-based services are the basis for communication capabilities.

  • BLE communication between the gateway module and a smart phone, allowing a phone app to:

    • Scan Wi-Fi access point services within range of the ARTIK gateway board

    • Pass along the user's selection and password to get connected to that Wi-Fi AP

    • Initiate device registration.

  • LWM2M communication between the gateway module and ARTIK Cloud, enabling:

    • Secure Device Registration (SDR) with ARTIK Cloud

    • Reception of over-the-air (OTA) updates from ARTIK Cloud. The updates can be .deb packages to apply to the gateway itself, or images to pass on to downstream edge node devices.

IoTivity/Thread network communication on the gateway module, courtesy of the ARTIK border router service, is optional. A management portal is served by the Edge Node Manager (ENM) allowing local access to all connected device information (including those devices not yet registered with ARTIK Cloud). An ENM Dashboard gives higher-level visibility over these devices. These packages have ble-onboarding and lwm2m-client as dependencies.

Phase 1: Connect to Wi-Fi access point

For this description to make sense, start by performing the on-boarding procedure, then take a look at the details involved.

The phone app uses a Bluetooth/BLE connection to exchange information with the ARTIK module. It does not use Wi-Fi to talk with ARTIK Linux modules.

  description                             Looks like this
1.


App grabs QR code image and converts it to text.
The QR code is in this format
_serial_number_,_wifi_mac_address_,_bt_mac_address_
where _bt_mac_address_ is $BLE_MAC in the gateway code.
The app now knows the BLE MAC address to pair with.
2. Press the BLE pairing switch on the ARTIK board (LED turns red).
The ARTIK board opens a BLE channel on its BT/BLE central controller.

The gateway BLE central controller sends out broadcast advertisement packets every 10ms with the
BLE primary service UUID of
FFFFFFFF-C0C1-FFFF-C0C1-$BLE_MAC
3. Hit Continue on the app, which will pair with the device by BLE MAC address. It does this quickly once it finds the service UUID being broadcast that matches the QR code value read.
4. Hit Connect to Wi-Fi on the app. The mobile app reads the "WIFI_LIST_CHARACTERISTIC_UUID" each time it wants to read a single Access Point from the list found by the gateway; when it finds "end", it knows it is done. The format is shown below.  

         Example first read

      {
        "ssid": "dahmani",
        "bssid": "00:37:b7:08:b5:d6",
        "security":"Open",
        "signal":-46.00
      }

         Example subsequent read

      {
        "ssid": "Livebox-c2ea",
        "bssid": "d0:84:b0:57:c2:ee",
        "security":"Secure",
        "signal":-50.00
      }

         Example final read

      {
        "ssid": "end",
        "bssid": "end",
        "security":"end",
        "signal":0
      }

When you click Connect to Wi-Fi, you get the list found by the gateway, as if you used:
connmanctl
> scan wifi
> services

The app only displays information from the gateway; it does not do a Wi-Fi scan itself.

With the list of available Wi-Fi networks, you choose one and provide its passphrase. The app sends the selected AP name and passphrase to the module, which adds it to its list just as with Connection Manager.

Network management. The network setting is retained and Wi-Fi is automatically started on each boot. If you need to review, change, or remove a connection, just use Connection Manager as always. The next time you reboot the module, it will use Connection Manager to automatically connect to your previously selected Wi-Fi AP. This happens even if the final step of registration to ARTIK Cloud failed during on-boarding.


The app waits for the Wi-Fi connection to succeed. It then uses all the information it collected to register the gateway to ARTIK Cloud (as described below).

Phase 2: Register Device with Cloud

The phone app interacts with the BLE on-boarding service through BLE GATT profile characteristic UUIDs. It used these in the first phase to do things like learn of the module BLE UUID, call for a Wi-Fi scan, etc. The app likewise uses these UUIDs during the registration process, which varies depending on whether you want to register with ARTIK Cloud or other clouds.

Using ARTIK Cloud. When it comes time for registering the Linux module to ARTIK Cloud, the phone app reads the ARTIK Cloud DEVICE_TYPE_ID_ characteristic UUID.

If it is an "s" module:

  1. The app starts the secure device registration (SDR) process by writing 1 to the START_REG_ characteristic.

  2. The BLE on-boarding service registers the device to ARTIK Cloud and updates the CHALLENGE_PIN_ characteristic.

  3. The app reads this characteristic and verifies the same with ARTIK Cloud, thus completing secure registration.

  4. The app writes 1 to the COMPLETE_REG_ characteristic.

  5. The BLE on-boarding service requests from ARTIK Cloud the Device ID and Device Token of the new device, and updates the corresponding characteristics.

If it is not an "s" module, the app cannot use the SDR flow. Instead:

  1. The app creates a device in ARTIK Cloud and retrieves the device credentials.
  2. The app passes the device credentials to the BLE on-boarding service.

BLE on-boarding installation files

You can edit the installed files to suit your application.

Directory: /usr/local/ble-onboarding/

BLE on-boarding launcher (start-launcher.sh) is responsible for launching the BLE Onboarding service on the gateway. For security reasons, the BLE service on ARTIK gateways is disabled by default, since there is no authentication mechanism in the BLE connection.

A button push (GPIO) is configured to launch the BLE service, which will quit once a timeout has been reached. Out-of-the box, button SW403 is configured to launch the service and LED400 will glow while the service is running. These defaults can be overridden in the start-launcher.sh script using environment variables.

LAUNCH_BUTTON_GPIO=122
STATUS_LED_GPIO=123
SERVICE_TIMEOUT_IN_SECONDS=300

If the launch button is pressed before the BLE onboarding service has terminated, it will be restarted with a fresh timeout.

BLE on-boarding service (start-service.sh) performs the secure device registration on the gateway by exposing a BLE profile to a BLE client such as the ARTIK mobile on-boarding app (or to your own custom app). Out-of-the-box, the BLE service broadcasts with a peripheral named ArtikOnBoarding. Device information defaults can be customized in the start-service.sh script using environment variables.

SERVICE_ID="FFFFFFFF-C0C1-FFFF-C0C1-$BLE_MAC"
ONBOARD_VENDOR_ID="Samsung"
SDR_DEVICE_TYPE_ID=dtc5ecf0abccaa428c853e144c964ad727
SDR_VENDOR_ID=$(head /dev/urandom | tr -dc A-Za-z0-9 | head -c 6)
MODEL=$(cat /etc/artik_release | grep -i MODEL | cut -c 7-)
ONBOARDING_SERVICE_NAME="ArtikOnBoarding"
ACTIONS_LED=38

Websocket demo client service (websocket-client.js) processes Actions from ARTIK Cloud. Use it as a template for writing your own handler.

Primary Service UUID

The primary service has a Service UUID of
FFFFFFFF-C0C1-FFFF-C0C1-$BLE_MAC
where $BLE_MAC is replaced by the 12 character Bluetooth adapter MAC address, providing each ARTIK gateway with a unique identifier. This Service UUID is also present in the broadcast advertisement packets that are sent every 10 ms.

Secondary Characteristic UUIDs

The following BLE UUIDs are the same for every Artik board. The full name of each has a suffix appended, like this: CHALLENGE_PIN_CHARACTERISTIC_UUID and A is Access type: Read/Write/Notify.

NameUUIDALENDesc
CHALLENGE_PIN_ 0000FFF1-0000-1000-8000-00805F9B34FB R 5 Obtained by BLE service after SDR begins
ACCESS_TOKEN_ 0000FFF2-0000-1000-8000-00805F9B34FB R 32 ARTIK Cloud Device Token obtained from SDR flow
DEVICE_TYPE_ID_ 0000FFF3-0000-1000-8000-00805F9B34FB R 32 ARTIK Cloud Device Type ID, set in start-service.sh
SDR_VENDOR_ID_ 0000FFF4-0000-1000-8000-00805F9B34FB R 22 Vendor Device ID, set in start-service.sh
START_REG_ 0000FFF5-0000-1000-8000-00805F9B34FB W 1
(int)
Starts SDR on gateway
COMPLETE_REG_ 0000FFF6-0000-1000-8000-00805F9B34FB W 1
(int)
Completes SDR on gateway
DID_ 0000FFF7-0000-1000-8000-00805F9B34FB R 32 Device ID
UID_ 0000FFF8-0000-1000-8000-00805F9B34FB R 32
STATUS_ FFFFFFFF-C0C1-FFFF-C0C1-201401000001 RN 32 Wi-Fi and SDR status:
see below
DETAILED_
STATUS_
FFFFFFFF-C0C1-FFFF-C0C1-201401000002 R 22 Detailed status:
see below
SSID_ FFFFFFFF-C0C1-FFFF-C0C1-201401000003 RN 22 Wi-Fi AP SSID, user-provided
AUTH_ FFFFFFFF-C0C1-FFFF-C0C1-201401000004 RW 6 Authentication type of AP:
OPEN
SECURE
PASSPHRASE_ FFFFFFFF-C0C1-FFFF-C0C1-201401000005 W 22 Passphrase of AP, user-provided
CHANNEL_ FFFFFFFF-C0C1-FFFF-C0C1-201401000006 R
COMMAND_ FFFFFFFF-C0C1-FFFF-C0C1-201401000007 R
VENDORID_ FFFFFFFF-C0C1-FFFF-C0C1-201401000008 R 32 set in start-service.sh
defaults to “Samsung”
DEVICEID_ FFFFFFFF-C0C1-FFFF-C0C1-201401000009 R 32 set in start-service.sh
WIFI_STATE_ FFFFFFFF-C0C1-FFFF-C0C1-201401000010 RN 10 Wi-Fi connection status on ARTIK gateway
IPADDRESS_ FFFFFFFF-C0C1-FFFF-C0C1-201401000011 R 16 IP address on ARTIK gateway
WIFI_LIST_ FFFFFFFF-C0C1-FFFF-C0C1-201401000012 R 512 List of APs available to the module
{
"ssid": "< SSID >",
"bssid": "< BSSID >",
"security": "OPEN|SECURE",
"signal": < SIGNAL >
}
CLOUD_
DEVICE_ID_
FFFFFFFF-C0C1-FFFF-C0C1-201401000013 W 32
CLOUD_
DEVICE_TOKEN_
FFFFFFFF-C0C1-FFFF-C0C1-201401000014 W 32


/* Status */
const (
  DISCONNECTED = "1"
  INITIALIZING = "2"
  CONNECTING   = "3"
  CONNECTED    = "4"
  FAILED       = "5"
  RECVD_PIN    = "6"
  RECVD_TOKEN  = "7"
)
 
/* Detailed Status */
const (
  NONE                        = "51" // "NONE"
  SET_SSID                    = "52" // "Set SSID"
  SET_AUTH                    = "53" // "Set auth type"
  WRONG_AUTH                  = "54" // "Wrong auth. type"
  SET_PSK                     = "55" // "Set PSK"
  SET_CHAN                    = "56" // "Conn. or set channel"
  AUTHING                     = "57" // "Authenticating"
  GETTING_IP                  = "58" // "Getting IP address"
  CONN_ESTAB                  = "59" // "Connection completed"
  PSK_NOT_REQ                 = "60" // "No PSK required"
  RECVD_CHALLENGE             = "61" // "Received Challenge"
  RECVD_DEVICE_TOKEN          = "62" // "Received Token"
  START_REGISTRATION_ERROR    = "63" // "Registeration Error"
  COMPLETE_REGISTRATION_ERROR = "64" // "Invalid Token"
  INVALID_SSID                = "65" // "Invalid SSID"
  WRONG_PASSWORD              = "66" // "Invalid Password"
  NO_IPADDRESS                = "67" // "Unable to get Ip"
  INTERNET_UNAVAILABLE        = "68" // "No Internet"
  INVALID_WIFI_STATE          = "69" // "Invalid wifi module state"
  SCAN_FINISH                 = "70" // "Wifi Scan Finish"
)

Manual Package Installation

For OS_3.0.0 and older images, and for Fedora images, the on-boarding package must be installed manually.

Make sure you follow all update steps including the repository and SDK installation. After updating, follow the short on-boarding package installation procedure below.

These instructions are for 32-bit Ubuntu platforms (ARTIK 530).

  1. Download the on-boarding package and copy it to your ARTIK root. The current package is preliminary and not yet part of the repository. Click here:
    >> Edge Node Manager Package
    Within the zip file, look under packages/ and you'll find the ble_onboarding_... file in the directory for your gateway module type.

  2. Install the on-boarding service. The current package version requires installation of a specific version of the ARTIK SDK, which may be a downgrade to your installed SDK. Use the Tab key to autocomplete the ble-onboarding... version you have copied.

    apt install libartik-sdk=1.7-0
    dpkg -i ble-onboarding... .deb
    apt -f install

    This last command fixes dependency issues that may come up, such as an outdated nodejs revision.
  3. Verify that that the service is running using the following command.

    systemctl status ble-onboarding

    If not, use enable in place of status, then reboot the board and check status again.


These instructions are for 64-bit Ubuntu platforms (ARTIK 710).

  1. Download the on-boarding package and copy it to your ARTIK root. The current package is preliminary and not yet part of the repository. Click here:
    >> Edge Node Manager Package
    Within the zip file, look under packages/ and you'll find the ble_onboarding_... file in the directory for your gateway module type.

  2. Install the on-boarding service. The current package version requires installation of a specific version of the ARTIK SDK, which may be a downgrade to your installed SDK. Use the Tab key to autocomplete the ble-onboarding... version you have copied.

    apt install libartik-sdk=1.7-0
    dpkg -i ble-onboarding... .deb
    apt -f install

    This last command fixes dependency issues that may come up, such as an outdated nodejs revision.
  3. Verify that that the service is running using the following command.

    systemctl status ble-onboarding

    If not, use enable in place of status, then reboot the board and check status again.


These instructions are for Fedora platforms.

  1. Download the on-boarding package and copy it to your ARTIK root. The current package is preliminary and not yet part of the repository. Click here:
    >> Edge Node Manager Package
    Within the zip file, look under packages/ and you'll find the ble_onboarding_... file in the directory for your gateway module type.

  2. Install the on-boarding service. Use the Tab key to autocomplete the ble-onboarding... version you have copied.

    dnf install libartik-sdk
    dnf install --allowerasing ble-onboarding-... .rpm
  3. Verify that that the service is running using the following command.

    systemctl status ble-onboarding

    If not, use enable in place of status, then reboot the board and check status again.

ENM-based On-boarding

ARTIK 030 modules programmed as Thread devices are on-boarded through the gateway by the Edge Node Manager.

Wi-Fi-based On-boarding

ARTIK 053 and 055 modules are on-boarded using a direct Wi-Fi link from the phone app. Refer to the Connect to the World article for details.

Last updated on: