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.

Name	UUID	A	LEN	Desc
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.

• Ubuntu 32-bit
• Ubuntu 64-bit
• Fedora

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.

• Prev: Onboarding/QR Codes
• Next: Printing QR Codes