Onboarding

To use the gateway and end node, you need to bind them with an owner who uses them. This binding process is called Onboarding. You need to perform the onboarding as a part of the initialization process.

By performing the onboarding, the thing will be able to leverage the features like sending commands and uploading the states. The user and group which can operate the thing will be also clarified in the onboarding process to ensure the security.

When onboarding, the following relationships will be defined to initialize the internal structure.

• The relationship between the gateway and its owner (user or group).

• The relationship between the end nodes and their owner (users or groups).

• The relationship between the gateway and end nodes.

In this section, we will explain how the onboarding works and show the related Thing Interaction Framework features.

Precondition

We assume that the gateway and end node (converter) have the following information.

• Gateway

  We assume that the gateway has the following information being set. The information can be preset as the factory setting or can be set when the gateway agent process is launched.

  • vendorThingID, username, and password

    The gateway needs to have its vendorThingID, username, and password (we will use gwVendorThingID, gwUsername, and gwPassword as examples on this page).

    The gateway username is used for authentication to allow the user to access the local REST API from the mobile app. The gateway password is used for securing the gateway related data on Thing Interaction Framework as well as the authentication for the local REST API.

  • The information of the application for the gateway

    We assume the application information (i.e., AppID) is preset on the gateway.

    Our design allows the application for the end node to be different from the one for the gateway to cover a scenario in which the end nodes manufactured by the third party are later added onto the gateway. To accommodate such a scenario, the AppID for the end node is designed to be set as a gateway API parameter.

• End Nodes/Converters

  We assume each end node has a unique vendorThingID so that they can be independently identified by the application. If the end node cannot generate its vendorThingID, the converter can generate a unique ID (e.g., UUID) and use it as the vendorThingID instead.

Onboarding Steps

The onboarding steps are different among the gateway app, the end node app, and the double-purpose app which works as both a gateway app and an end node app.

• Onboarding with Gateway App

  Take only the steps described in Onboarding Gateway on the gateway app.

• Onboarding with End Node App

  Take the steps described in Onboarding Gateway and Onboarding End Node on the end node app. Repeat the steps in Onboarding End Node to onboard multiple end nodes.

  The gateway onboarding is done on each end node app.

• Onboarding with Double-Purpose App

  Take the steps described in Onboarding Gateway and Onboarding End Node on the double-purpose app. Repeat the steps in Onboarding End Node to onboard multiple end nodes.

Onboarding Gateway

First, onboard the gateway only after its installation.

See the below figure for the onboarding flow. APIs on the mobile app are in red and parameters are in green. The numbers in the figure correspond to those in the following description.

1. The user downloads and installs the mobile app to their smartphone after the gateway is released.

2. The user installs the gateway hardware and connects it to the network. This will make the mobile app and gateway possible to communicate on the local network (e.g. Wi-Fi).

3. The mobile app creates a user who will become the owner of the gateway and end node. The mobile app then gets the owner's access token. This access token is denoted as ownerAccessToken in the figure.

4. The mobile app logs into the gateway to access the gateway via the local API. The mobile app is authenticated with the gateway username gwUsername and the gateway password gwPassword to get the access token of the gateway agent.

5. The mobile app sends the onboarding request to the gateway.

6. The gateway further sends the onboarding request to Thing Interaction Framework. The gateway's vendorThingID gwVendorThingID and password gwPassword are set in the request to secure the gateway.

7. As a result of the onboarding, the gateway receives its thingID gwThingID (together with the gateway access token and MQTT connection information) from Thing Interaction Framework.

8. As the response to the request in Step 5, the gateway returns the gwThingID to the mobile app.

9. The mobile app sends its onboarding request to Thing Interaction Framework. The owner's access token ownerAccessToken, the gateway's thingID gwThingID and password gwPassword are set in the request. Thing Interaction Framework will bind the owner user to the gateway.

The gateway is bound to the mobile app after these steps, and we are now ready to add an end node.

Please note that the gateway username gwUsername and password gwPassword need to be entered to the mobile app in some way in order to take Step 4 and 9. You can use any method such as getting information from the sticker on the case of the gateway and entering it to the mobile app.

Onboarding End Node

We onboard the end node as follows after the gateway onboarding is completed. These steps need to be taken every time we add a new end node.

1. The user installs the end node. The corresponding converter is also installed on the gateway at the same time so that the end node can connect to the gateway.

2. The end node connects to the gateway automatically or with some user manipulation. The AppID appid of the application for the end node and the end node's vendorThingID endVendorThingID are sent as the request parameters. The AppID is used to determine the corresponding application since each end node can use different applications.
   When the end node is connected to the gateway, the gateway agent will internally store the end node's vendorThingID in the list of "unregistered" nodes.

3. When the end user initiates the end node onboarding from the mobile app, the mobile app sends a request to fetch the list of "unregistered" nodes via the gateway's local REST API. The list contains end nodes that are not yet onboard.

4. As the response to Step 3, the gateway returns the list of end node's vendorThignIDs (in our example, one endVendorThingID is returned).

5. The end user selects the end node to onboard from the list. The end user also sets the password of the end node (in our example, we use the password endPassword).

6. The mobile app sends the onboarding request. The owner's access token ownerAccessToken obtained as the result of the gateway onboarding, the target end node's vendorThingID endVendorThingID, the password endPassword, and the gateway's thingID gwThingID are sent to Thing Interaction Framework.

7. As the response to Step 6, Thing Interaction Framework returns the target end node's thingID endThingID.

8. The mobile app notifies the endThingID to the gateway via the gateway agent's local REST API. The gateway agent can later get the access token of the end node from Thing Interaction Framework.

You can take Step 1 and 2 before the steps of Onboarding Gateway for the end node app.