Partner Portal TutorialPartner Portal is a web-based self-service portal that is integrated with...

1553-5/CXP9040776 Uen E1

Partner Portal Tutorial

IoT Enablement

User Guide

1553-5/CXP9040776 Uen E1

Copyright

© T-Mobile AB 2019. All rights reserved. No part of this document may be reproduced in any form without the written permission of the copyright owner.

Disclaimer

The contents of this document are subject to revision without notice due to continued progress in methodology, design and manufacturing. T-Mobile shall have no liability for any error or damage of any kind resulting from the use of this document.

Trademark List

All trademarks mentioned herein are the property of their respective owners. These are shown in the document Trademark Information.

Contents

1553-5/CXP9040776 Uen E1 | 2019-11-25

Contents

1 About This Document 1

1.1 Revision Information 1

1.2 Target Audience 1

2 What Is Partner Portal? 3

3 Overview 4

3.1 Developer Portal Features 5

4 Partner and User Management 7

4.1 Roles and Permissions of System Administrators 7

4.2 Roles and Permissions of Partner Users 8

4.3 Service Details 9

5 Resource Management 12

5.1 Device Type Management 12

5.2 Device Management 21

5.3 Device Job Management 35

6 API Access Management 53

6.1 API Keys 53

6.2 OAuth Registration 54

7 API Directory 55

8 API Dashboard 56

9 Device Dashboard 57

10 Device Client Examples 58

11 Features Only for Administrators 60

11.1 Partner Assignement 60

11.2 LwM2M Server and ACL Management 61

11.3 LwM2M Server Configuration 61

11.4 Enable API Access for a Partner 62

11.5 Approve API Key Creation 62

11.6 Block or Unblock an API Key 63

11.7 Partner Topic Permission Management 64

Contents

1553-5/CXP9040776 Uen E1 | 2019-11-25

12 Example Scenarios 65

12.1 On-Board Devices on Partner Portal 65

12.2 Update Devices on Partner Portal 74

12.3 Create FOTA Job for LwM2M Device 75

12.4 Configure LwM2M Servers and ACL on Device Type 77

12.5 Getting Started with API Access 78

12.6 Getting Started with a Real Device 81

13 Life Cycle of Entities 92

13.1 Life Cycle of Partner 92

13.2 Life Cycle of Partner User 93

13.3 Life Cycle of Device and Device Type 94

13.4 Life Cycle of API Key 96

13.5 Life Cycle of OAuth Registration 97

14 Appendix - Error Code Rules 99

15 Appendix - Permissions of System Administrators 100

15.1 Admin Permissions 100

15.2 On-behalf Permissions 100

16 Appendix - Permissions of Partner Users 103

16.1 API Key Permissions 103

16.2 Device Permissions 103

16.3 Device Type Permissions 104

16.4 OAuth Registration Permissions 104

16.5 User Management Permissions 105

16.6 Data Storage Permission 105

About This Document

1 1553-5/CXP9040776 Uen E1 | 2019-11-25

1 About This Document

This document provides a brief introduction to the features that Partner Portal supports in IoT Enablement.

1.1 Revision Information

The following table shows the changes in recent revisions of this document. Other than editorial changes, this document has been revised as follows:

Table 1 Revision Information

Revision Section Change

E1 Prepare Partner Account on page 68

Updated steps for topic permission enablement.

Partner Topic Permission Management on page 64

New Topic

MQTT and CoAP Device Data Management on page 32

New Topic.

LwM2M Device Data Management on page 32

Added LwM2M to the title and removed the limitation that Device Data Management is only for LwM2M devices.

Admin Permissions on page 100

Added a note to describe that system admins can only manage assigned partners.

Partner Assignement on page 60

New section.

Assign Partners to Admin Users on page 60

New section.

View Associated Admin Users of a Partner on page 60

New section.

1.2 Target Audience

This document is intended for the users who want to understand the use of Partner Portal in IoT Enablement. They are supposed to have a knowledge in the following areas:

— Protocols that are related to device managements, such as OMA LwM2M,

MQTT, and NIDD.

About This Document

2 1553-5/CXP9040776 Uen E1 | 2019-11-25

— REST API

3 1553-5/CXP9040776 Uen E1 | 2019-11-25

What Is Developer Portal?

2 What Is Partner Portal?

Partner Portal is a web-based self-service portal that is integrated with other components. On Partner Portal, developers can manage resources.

Exposed APIs are displayed on Partner Portal. Therefore, developers can browse and try out all available APIs. Also, developers can obtain and manage credentials, which developers can populate to applications. By doing so, APIs can be called to access specific end user data.

Additionally, API usage status related to those applications is monitored and displayed on Partner Portal.

4 1553-5/CXP9040776 Uen E1 | 2019-11-25

What Is Developer Portal?

3 Overview

Partner Portal, which provides the central provisioning and management GUI, can be integrated with Dispatcher, CDM, and SCEF. Partner Portal allows developers to on-board a device that can communicate with northbound applications through Dispatcher, CDM, and SCEF over different protocols.

The following figure provides an overview of the integrated components and illustrates the device communication with northbound applications in detail:

Figure 1 System Overview

Integrated Components

— Connected Device Manager (CDM)

CDM provides device management functionality as well as secure bootstrap and device registration. It supports single/batch execution and handling of device management jobs.

— Dispatcher

5 1553-5/CXP9040776 Uen E1 | 2019-11-25

Overview

Dispatcher provides network and device adaptation functionality that enables a high performance bidirectional communication between applications and devices. Dispatcher translates the protocols between applications and devices.

— Service Capability Exposure Function (SCEF)

SCEF provides a means to securely expose the services and capabilities provided by 3GPP network interfaces through APIs to Application Servers.

— Partner Portal

Partner Portal provides a web-based self-service GUI portal for central provisioning and management. See Partner Portal Features on page 5 for details.

Device Communications

Possible scenarios of device communication with northbound applications are as follows:

— Through Dispatcher over MQTT

— Through Dispatcher and CDM over LwM2M

— Through Dispatcher and CDM over CoAP

— Through Dispatcher and CDM over any combination of the following protocols:

— MQTT

— LwM2M

— CoAP

In scenarios when LwM2M and CoAP are involved, CDM and Dispatcher must be integrated in terms of LwM2M and CoAP functions.

— Through SCEF over NIDD

For details about how to on-board devices on Partner Portal, see On-Board Devices on Partner Portal on page 65.

3.1 Partner Portal Features

The features of Partner Portal in this system is summarized as follows:

— Partner and User Management

• Roles and permissions of System Administrators

6 1553-5/CXP9040776 Uen E1 | 2019-11-25

Overview

• Roles and permissions of Partner Users

See Partner and User Management on page 7 for details.

— Resource Management

• Device Type Management

• Device Management

• Device Job Management

See Resource Management on page 12 for details.

— Download Examples for Device Client Development

See Device Client Examples on page 58 for details.

— API Access Management

• API Key Management

• OAuth Registration Management

See API Access Management on page 53 for details.

— API Try-out

See API Directory on page 55 for details.

— API Usage Monitoring

See API Dashboard on page 56 for details.

— Device Status Monitoring

See Device Dashboard on page 57 for details.

— Service details

• Viewing enabled APIs

• Configuring event notifications See

Enabled APIs on page 9 for details.

7 1553-5/CXP9040776 Uen E1 | 2019-11-25

Partner and User Management

4 Partner and User Management

Partner Portal supports multiple partners. This function involves users, namely, System Administrator, Contact Person, and Developer, as well as an entity Partner. The partner and user management is implemented through roles and permissions. Users in Partner Portal can have different permissions. The permissions can be grouped into different roles on demand. For example, a system administrator can create partners and developers only when the system administrator has such permissions.

The following table details information on partners and users:

Table 2 Partner Portal Partners and Users

4.1 Roles and Permissions of System Administrators

On Partner Portal, users can perform operations based on their assigned permissions. A group of permissions constitutes a role. The role name and the group of permissions are user-defined. A system administrator can have more than one role.

The permissions available for system administrators fall into the following two categories:

— Admin Permissions

The permissions that are common to a system administrator.

— On-behalf Permissions

The permissions that allow system administrators operate on behalf of Partner Users.

Entity/User Description

System Administrator A user created in Account Manager as the system administrator. The permissions of system administrator are selected when the account is created in Account Manager. For instructions on how to create system administrator in Account Manager, see Create Administration Account on page 66. More than one system administrator can exist.

Partner An entity that is usually an organization or a company, created by an administrator or with self-service.

Note: A partner is an entity, not a user and thus does not have roles or permissions.

Contact Person A user in Developer Portal, who is the contact person of a Partner. A contact person belongs to only one partner. A partner has only one contact person but many developers.

Developer A user in Developer Portal that can be created as follows:

— Partner Developer: Created by the contact person of a partner. In this case, the created developers belong to this partner and only have access to resources and API access of this specific partner.

8 1553-5/CXP9040776 Uen E1 | 2019-11-25


The following table lists the permissions that are available for System Administrators. For details about the permissions, see Appendix - Permissions of System Administrators on page 100.

Table 3 Permissions Available for System Administrator

Category Permission

Admin Permissions Manage Partners and Developers

View Devices

Manage Device Types

Manage API Keys

Manage LwM2M Servers

On-behalf Permissions API Key Permissions View API Keys Create API Keys Update API Keys Delete API Keys

Device Permissions View Devices Create Devices Update Devices Delete Devices Export Devices Read and Observe LwM2M Data Write and Execute LwM2M Data Read and Observe CoAP Data Revoke and Renew Certificates

Device Type Permissions View Device Types Create Device Types Update Device Types Delete Device Types FOTA SOTA Update LwM2M Server Configuration

OAuth Registrations Permissions

View OAuth Registration Create OAuth Registration Update OAuth Registration Delete OAuth Registration

User Management Permissions

View Users Create Users Update Users Delete Users

Data Storage Permission Data Storage

4.2 Roles and Permissions of Partner Users

A partner user refers to a contact person or developer of a partner. By default, a contact person has all permissions available for a developer, and also additional permissions to perform the following operations:

— View, create, delete, edit, deactivate, and restore developers for a partner.

— View, create, delete, and edit roles.

— Edit company (partner) information.

Note:

9 1553-5/CXP9040776 Uen E1 | 2019-11-25


The view permission is the prerequisite of the other permissions. For example, if you want to create, update, or delete API keys, you need to have the view permission first.

The following table lists the permissions that are available for Partner Users. For details about the permissions, see Appendix - Permissions of Partner Users on page 103

Table 4 Permissions Available for Partner Users

Category Permission

Permissions of Partner Users API Key Permissions View API Keys Create API Keys Update API Keys Delete API Keys

Device Permissions View Devices Create Devices Update Devices Delete Devices Export Devices Read and Observe LwM2M Data Write and Execute LwM2M Data Read and Observe CoAP Data Revoke and Renew Certificates

Device Type Permissions View Device Types Create Device Types Update Device Types Delete Device Types FOTA SOTA

OAuth Registrations Permissions View OAuth Registration Create OAuth Registration Update OAuth Registration Delete OAuth Registration

User Management Permissions View Users Create Users Update Users Delete Users

Data Storage Permission Data Storage

4.3 Service Details

The Service Details page allows a partner to check the enabled services and set service preferences.

4.3.1 Enabled APIs

A partner can check the enabled APIs on the Service Details > APIs page. The enabled APIs display with the request limits, including the daily requests and requests per second.

APIs are enabled for a partner by System Administrator. For instructions, see Enable API Access for a Partner on page 62.

10 1553-5/CXP9040776 Uen E1 | 2019-11-25


Note: After an API is enabled for a partner, API keys or OAuth registration can be used to control the access of the API. For instructions, see API Access Management on page 53.

4.3.2 Event Notifications

A partner can check and update the configuration for LwM2M device event notifications on the Service Details > Events page.

For details about the configuration, see Device Event Notification Configuration on page 10.

4.3.2.1 Device Event Notification Configuration

Event notifications for LwM2M devices are allowed to be sent upon bootstrap and registration operations.

Notifications are supported for the following events:

— Bootstrap: When LwM2M Client performs bootstrap, a notification is sent out once bootstrap is finished.

— First Time Register: After on-boarding a device, a notification is sent out when the Lwm2M Client registers with the LwM2M Server at first time.

— Register: Subsequent registrations after first time registration.

— Register Update: A notification is sent out when LwM2M Server receives registration update.

— De-register: A notification is sent out when LwM2M Server receives de- register operation.

— Registration Expired: A notification is sent out when the registration of the LwM2M Client expires.

— Sleeping: A notification is sent out when the LwM2M Client is going to sleep.

The following items can be configured for device event notifications:

— Whether to enable the notification for LwM2M device events.

— The event types for which the partner receives event notifications.

— Whether to include the field objectLinks in the event notifications for the event types First Time Register, Register, and Register Update.

The field objectLinks lists the Objects supported and Object Instances available on the LwM2M Client. The value follows the link format as specified in https://tools.ietf.org/html/rfc6690.

https://tools.ietf.org/html/rfc6690

11 1553-5/CXP9040776 Uen E1 | 2019-11-25


The event notification configuration for LwM2M devices is accessible with the following paths:

— For system administrators: Partners and Developers > Partners > {Partner} >

Events

— For partners: Service Details > Events

The event notification configuration for LwM2M devices can also be configured at the device type level creating or editing a LwM2M device type.

12 1553-5/CXP9040776 Uen E1 | 2019-11-25


5 Resource Management

Resources including devices and device types can be managed on Partner Portal.

5.1 Device Type Management

Devices can be managed on Partner Portal. A device type, which is similar to a data collection model, is associated with devices.

Partner Users with Device Type Permissions are allowed to manage device types. For details on operations supported for device type management and the permission required to perform a certain operation, see Device Type Permissions on page 104.

System administrators are also allowed to manage device types on behalf of Partner Users. For details on the on-behalf permissions on device types for system administrators, see Device Type Permissions on page 101.

5.1.1 Device Type Onboarding

Users with the permission of Create Device Types are allowed to onboard device types on Partner Portal. Configurations for a device type vary with the communication protocols supported by the device type.

Table 5 Configuration Items for Device Type Info

Configuration Item Description Possible Value

Device Type Name Mandatory.

Specifies the name of a device type.

A string of characters

Device Type ID An identifier that uniquely identities a device type.

Automatically generated when a device type is created.


Protocols Mandatory.

The communication protocols through which devices associated with the device type communicate with the server.

A device type must support at least one protocol. A device type

Options for protocols are as follows:

— MQTT

— LwM2M

— CoAP

13 1553-5/CXP9040776 Uen E1 | 2019-11-25

Resource Management


can support a combination of multiple protocols.

— NIDD (Payload Agnostic)

Example values:

— MQTT, LwM2M, CoAP, and NIDD (Payload Agnostic)

— MQTT and LwM2M

— CoAP

Device Type Image Specifies an image to identify a device type. The maximum size of the image is 50 KB. Supported image formats include: *.gif, *.jpg, *.jpeg, *.png, *.jpe, *.html, *.htm, *.jfif, *.dib.

An image

Device Identification Attributes identify devices associated with a device type. If all devices of the device type share a common value for an attribute, the value can be set at the device type level for all associated devices. If devices of the device type have different values for an attribute, the attribute is selected and left blank at the device type level so that values can be set for specific devices at the device level.

Table 6 Configuration Items for Device Identification Attributes

Attribute Name Description Possible Value

Manufacturer OUI The Organizational Unique Identifier (OUI) of a manufacturer. OUI is a 24-bit number that uniquely identifies a manufacturer. Applicable only if the supported Protocols include LwM2M.

Mandatory for a device type that supports LwM2M protocol.


Serial Number A string that specifies the Serial Number.


Description Description of a device associated with the device type.


14 1553-5/CXP9040776 Uen E1 | 2019-11-25

Resource Management


Manufacturer Human readable manufacturer name.


Model A manufacture specified string that specifies the model identifier.


Datastorage Specifies whether to enable or disable data storage for devices.

— Enable

— Disable

Custom Attributes Specifies custom attributes to identify the device type. For each custom attribute, Attribute Name and Immutable Value are specified. The value specified by Immutable Value cannot be changed at the device level.

— Attribute Name: A string of characters

— Immutable Value: A string of characters

Protocol Specific Configurations

Configurations for a device type vary with the communication protocols supported by the device type.

For a device type that supports the MQTT protocol, Data Object needs to be configured to specify the format of the device payload.

Table 7 MQTT Specific Configurations


Data Object Specifies the format of device payload.

JSON

JSON Data Object

Sensor A string that specifies the name of a MQTT sensor.

Applicable only if Data Object is JSON.

A string of characters, such as "GPS"

Sensor Resource

A string that specifies the name of a resource on a MQTT sensor.


A string of characters, such as "Latitude/ longitude"

Type Specifies the type of the value for a sensor resource. Supported options include:

— Number

— String

15 1553-5/CXP9040776 Uen E1 | 2019-11-25

Resource Management


String, Number, and Boolean.


— Boolean

For a device type that supports the CoAP protocol, Data Object and Delivery Mechanism need to be configured. Considering that CDM can send messages of CoAP devices to an external application system, Callback Parameters need to be configured to define the application server callback parameters to receive requests from devices associated with this device type.

Table 8 CoAP Specific Configurations


Delivery Mechanism Mandatory.

Specifies the data delivery channel of devices.

— IP data

— Non-IP data

IP data and Non-IP data

Data Object Specifies the format of device payload.

— JSON (Undefined Object): JSON format with undefined object. No object files need to be imported.

— Raw: Unstructured or unformatted repository data. No object files need to be imported.

Callback Parameters

Applicatio n Server Callback URL

Specifies the destination to which CoAP messages are sent.

A Callback URL

Security Specifies the security mode for the callback authentication.

— No Security

— Credential

Username Specify the username of the application server for callback authentication. Applicable if Security for Callback Parameters is Credential.


16 1553-5/CXP9040776 Uen E1 | 2019-11-25

Resource Management


Password Specify the password of the application server for callback authentication. Applicable if Security for Callback Parameters is Credential.


For a device type that supports the LwM2M protocol, Data Object and Delivery Mechanism need to be configured.

Table 9 LwM2M Specific Configurations


Delivery Mechanism Mandatory.

Specifies the data delivery channel of devices.

— IP data

— Non-IP data

— IP data and Non-IP data

Data Object Mandatory.

Specifies the resources of the device type that can be accessed and updated. Only XML files can be imported. Example XML schema can be downloaded from the link provided on Partner Portal.

An XML file containing defined objects needs to be imported.

For a device type that supports the LwM2M protocol, event notifications are supported to be configured.

Table 10 Event Notification Configurations


Receive Notification Specifies whether to enable the notification for the selected event types.

— Yes

— No

Event Types Specifies the event types for which to receive event notifications.

A group of event types.

17 1553-5/CXP9040776 Uen E1 | 2019-11-25

Resource Management


Supported event types are as follows:

— Bootstrap: When LwM2M Client performs bootstrap, a notification is sent out once bootstrap is finished.

— First Time Register: After on-boarding a device, a notification is sent out when the Lwm2M Client registers with the LwM2M Server at first time.

— Register: Subsequent registrations after first time registration.

— Register Update: A notification is sent out when LwM2M Server receives registration update.

— De-register: A notification is sent out when LwM2M Server receives de- register operation.

— Registration Expired: A notification is sent out when the registration of the LwM2M Client expires.

— Sleeping: A notification is sent out when the LwM2M Client is going to sleep.

Note:

18 1553-5/CXP9040776 Uen E1 | 2019-11-25

Resource Management


For the event types First Time Register, Register, and Register Update, specify to receive notifications containing the objectLinks field by checking the objectLinks option.

5.1.2 Device Type Update

Partner users with the permission of Update Device Types are allowed to update device types on Partner Portal.

Configuration Item Editable or Not

Remarks

Device Type Info

Device Type Name Yes N/A

Device Type ID No N/A

Protocols Yes A device type can be edited to support a different protocol or different numbers of protocols.

Examples:

— An MQTT device type can be updated to support both the MQTT and LwM2M protocols.

— A device type that supports both MQTT and LwM2M protocols can be updated to

19 1553-5/CXP9040776 Uen E1 | 2019-11-25

Resource Management


Remarks

support the MQTT protocol only.

The updates on the device type take effect after the changes are saved. For exiting devices that are associated with the device type, the updates are not validated until the devices are synchronized with the device type manually.

Device Type Image Yes N/A

Device Identification Attributes Yes Device type attributes can be updated, added and removed.

If the attributes at device type level are changed, the updates are visible at device level.

MQTT Specific Configuration s

Data Object Yes Data objects for an existing protocol can be updated, added and removed. The data objects are defined in device type. Changes are visible at device level.

20 1553-5/CXP9040776 Uen E1 | 2019-11-25

Resource Management


Remarks

CoAP Specific Configuration s

Delivery Mechanism Yes A device type can be edited to support a different delivery mechanism or different numbers of delivery mechanisms.

Data Object N/A

Callback Parameters N/A

LwM2M Specific Configuration s

Delivery Mechanism Yes A device type can be edited to support a different delivery mechanism or different numbers of delivery mechanisms.

Data Object Data objects for an existing protocol can be updated, added and removed. The data objects are defined in device type. Changes are visible at device level.

Events Receive Notification

A LwM2M device type can be edited to update the device event notifications.

Event Types

For details about configuration items, see Device Type Onboarding on page 12.

21 1553-5/CXP9040776 Uen E1 | 2019-11-25

Resource Management

Note: Changes to a device type automatically apply to newly created devices associated with the device type . Manual synchronization is needed to apply the changes of the device type to the existing devices associated with the device type.

5.2 Device Management

Devices can be managed on Partner Portal. Devices are identified by names and IDs. A device must be associated with a device type. Before the creation or batch import of devices, a device type needs to be created.

Partner Users with Device Permissions are allowed to manage device. For details on operations supported for device management and the permission required to perform a certain operation, see Device Permissions on page 103. System administrators are also allowed to manage devices on behalf of Partner Users. For details on the on-behalf permissions on devices for system administrators, see Device Permissions on page 101.

5.2.1 Device On-boarding

Users with the permission of Create Devices are allowed to on-board devices on Partner Portal. Configurations of devices vary with the communication protocols supported by the associated device type.

Table 11 Configuration Items for Device Info


Device ID Specifies the ID of a device.

Note:

The value of this parameter can be automatically generated by the system or defined by the user.

— Set device ID: A string of characters. An example is dg2a3e983d0b7fe2q eeycw6esw1h.

— Use Auto- generated device ID: A string of characters. An example is dg6e837774178d671 k1tyys9prd4g.

Device Type Specifies the device type associated with the device.

Configuration items of devices vary with the communication protocols supported by

A created device type available in the list.

22 1553-5/CXP9040776 Uen E1 | 2019-11-25

Resource Management


the associated device type.

Device Name Specifies the name of a device.

A string of characters. An example is LwM2M-MQTT.

Device Identification Attributes identify a device. If an attribute is specified at the device type level, it is read-only for a device. If an attribute is selected and left blank at the device type level, the value of it can be specified at the device level.

Table 12 Configuration Items for Device Identification Attributes


Manufacturer OUI The Organizational Unique Identifier (OUI) of a manufacturer. OUI is a 24-bit number that uniquely identifies a manufacturer. Applicable only if the supported Protocols include LwM2M.

Mandatory for a device type that supports LwM2M protocol.


Serial Number A string that specifies the Serial Number.


Description Description of a device associated with the device type.


Manufacturer Human readable manufacturer name.


Model A manufacture specified string that specifies the model identifier.


Datastorage Specifies whether to enable or disable data storage for devices.

— Enable

— Disable

Custom Attributes Specifies custom attributes to identify the device type. For each custom attribute, Attribute Name and Immutable Value are specified. The value specified by Immutable Value cannot be

— Attribute Name: A string of characters

— Immutable Value: A string of characters

23 1553-5/CXP9040776 Uen E1 | 2019-11-25

Resource Management


changed at the device level.

Protocol-Specific Configuration Items

Device configuration items vary with the protocols supported by the associated device type. NIDD specific configurations are applicable only if the device type supports NIDD protocol, CoAP over NIDD or LwM2M over NIDD.

Table 13 MQTT-Specific Configuration Items


MQTT Data Object Specifies the format of device payload.

This item is defined at the device type level. For details on the configuration of this item, see Device Type Management on page 12.

Read-only

MQTT Security Specifies the security mode for the device to communicate with Partner Portal. Options for this item are as follows:

— X.509 certificate

Communication between the device and Partner Portal is protected by X.509 certificate. The X.509 certificate can be automatically generated. Also, an encoded Certificate Signing Request (CSR) can be used to request the X.509 certificate while keeping the private key secret.

CSR contains the identification of the device. The FQDN domain name of CSR must be in the format of <deviceId>_mqtt.

— Credential (Not

Secure)

X.509

certificate:

— Automatically generate X.509 certificate

— Manually input an encoded CRS to request the X.509 certificate

Credential (Not Secure):

— Manually input a password

— Automatically generated with the specified Password Length

24 1553-5/CXP9040776 Uen E1 | 2019-11-25

Resource Management


Password can be manually input in the text box or automatically generated with the specified Password Length. The maximum length of the password is 256 characters.

Table 14 CoAP Specific Configuration Items

Configuration Item Description Example Value

CoAP Data Object Specifies the format of device payload.


Read-only

Callback Parameters Specifies the application server callback parameters to receive requests from device. Defined at the device type level. For details on the configuration of this item, see


Read-only

CoAP Security Specifies the security mode for the device to communicate with the servers. Options for this item are as follows:

— No Security

— PSK

Specifies to use pre-shared key to secure the DTLS PSK communication of the device with the servers. Text Code can be automatically generated with a specified Code Length.

PSK:

— Input Hex or Text Code: A text or hexadecimal string of characters

— Automaticall y GENERATE TEXT CODE with a specified Code Length

25 1553-5/CXP9040776 Uen E1 | 2019-11-25

Resource Management

Configuration Item Description Example Value

The maximum length of code is 256 characters or hex bytes, and hex code must start with “0x”.

Table 15 LwM2M Specific Configuration Items


LwM2M Data Object Specifies the format of device payload.


Read-only

LwM2M Server Specifies the LwM2M Servers with which the device communicates.

This item is defined at the device type level. For details on the configuration of this item, see Configure LwM2M Servers and ACL on Device Type on page 77.

Read-only

LwM2M Security

Specifies whether to enable client initiated bootstrap.

This item is applicable if the LwM2M Server is not configured within the LwM2M Client or attempts to perform the Register operation with LwM2M Servers have failed. The Client Initiated Bootstrap requires a LwM2M Bootstrap-Server Account preloaded in the LwM2M Client.

— Enable Yes, enable client initiated bootstrap

— Disable Yes, enable client initiated bootstrap

Bootstrap Security

Specifies the security mode for the client initiated bootstrap.

PSK:

— Input Hex or Text Code: A text

26 1553-5/CXP9040776 Uen E1 | 2019-11-25

Resource Management


This item is applicable if Bootstrap Request is enabled.

or hexadecimal string of characters.

— Automatically GENERATE TEXT CODE with a specified Code Length.

— No Security

— PSK

Specifies to use pre- shared key to secure the DTLS PSK communication of the device with the servers. Text Code can be automatically generated with a specified Code Length.


LwM2M Data Security

Specifies the security mode for the device to communicate with the servers. Options for this parameter are as follows:

PSK:

— Input Hex or Text Code: A text or hexadecimal string of characters.

— Automatically GENERATE TEXT CODE with a specified Code Length.

RPK:

— Public Key: A string of characters.

— Private Key: A string of characters.

— No Security

— PSK

Specifies to use pre- shared key to secure the DTLS PSK communication of the device with the servers. Text Code can be automatically generated with a specified Code Length.


— RPK

27 1553-5/CXP9040776 Uen E1 | 2019-11-25

Resource Management


RPK can be automatically generated.

— X.509 certificate

The X.509 certificate can be automatically generated. Also, an encoded Certificate Signing Request (CSR) can be used to request the X.509 certificate while keeping the private key secret.

X.509 certificate:

— Automatically generate X.509 certificate.

— Manually input an encoded CRS to request the X.509 certificate.

An NIDD config request must be sent to SCEF to register an NIDD device. Either the MSISDN or External-ID is used for identifier in the NIDD config request. The identifier can be specified when on-boarding the NIDD device. The identifier can also be specified through updating the NIDD device after on-boarding.

Table 16 NIDD Specific Configuration Item


Device Identification

Enabled Specifies whether to set the identifier while on- boarding an NIDD device.

Enabled

— Yes

— No

Identificatio n

Specifies the identifier of a device. Options for this item are as follows:

— MSISDN

The Identifier identifies a subscription associated to an IMSI.

— MSISDN:

A string of characters. An example of MSISDN is 86137888888

88.

— External-ID

— External-ID:

An External Identifier identifies a subscription associated to an IMSI. The External Identifier shall be in the format of username@realm as specified in clause 2.1 of IETF RFC 4282.

A string of characters. An example of External-ID is 123456789@d

omain.com.

28 1553-5/CXP9040776 Uen E1 | 2019-11-25

Resource Management


Application Use the predefined Application

Specifies whether to use the predefined application to trigger the NIDD config request to register the NIDD device to SCEF.

Use the predefined Application

— Yes

— No

Application ID

Specifies the identifier of the SCS/AS.

A string of characters.

Destination Address

Specifies the callback URL of the SCS/AS to receive requests from the device.

A callback URL.

APN Specifies the Access Point Network (APN) identifier for NIDD.

A string of characters.

5.2.2 Device Update

Partner users with the permission of Update Devices are allowed to update devices on Partner Portal.

Configuration Item Editable or Not Remarks

Device Info Device ID No N/A

Device Type No N/A

Device Name Yes N/A

Device Identification Attributes

Yes If an attribute is specified with a value at the device type level, it is read-only for a device and cannot be updated. If an attribute is selected and left blank at the device type level, the value of it can be specified and updated for an associated device.

Synchronization with the associated device type is required for a device if a new attribute without

29 1553-5/CXP9040776 Uen E1 | 2019-11-25

Resource Management


default value is added for the device type. A value must be specified for the new attribute during synchronization.

MQTT Specific Configurations

Data Object No N/A

Security Yes Following operations are supported:

— Change the security mode.

— Regenerate certificates for MQTT.

— Reset password for MQTT credential.

CoAP Specific Configurations

Data Object No N/A

Callback Parameters

No N/A



— Regenerate the PSK credential for a CoAP device.

LwM2M Specific Configurations

Data Object No N/A

LwM2M Server No N/A



30 1553-5/CXP9040776 Uen E1 | 2019-11-25

Resource Management


— Regenerate the certificate for a LwM2M device.

— Update PSK for a LwM2M device.

— Update RPK for a LwM2M device.

NIDD Specific Configurations

Device Identification

Yes N/A

Application Yes N/A

Note: Update device security will block the device traffic.

When the associated device type is updated, changes need to be applied to a device manually for synchronization. If an existing protocol is removed, corresponding protocol configurations are removed during the synchronization. For example, if the protocol LwM2M is removed for the associated device type of a device, the LwM2M specific configurations will be removed for a device during the synchronization. If new protocols are added to the associated device type, corresponding Security settings for the added protocols are required to be specified during the synchronization. For details on configurations of protocol specific Security configurations, see Device Management on page 21.

5.2.3 Batch Device Update

The identifiers of NIDD devices can be updated in batch mode with CSV files. By default, a maximum of 100 devices can be updated in one batch of a CSV file.

The information of devices added to a CSV file for batch import must follow the rules of the CSV template downloaded from Partner Portal. Column headers in the CSV files indicating device attributes are as follows:

— deviceID: Specifies the unique ID of a device. Leave it blank to auto generate ID for the device.

— MSISDN: Specifies the Identifier identifies a subscription associated to an IMSI.

— External-ID: Specifies an External Identifier identifies a subscription associated to an IMSI. The External Identifier is in the format of username@realm as specified in clause 2.1 of IETF RFC 4282.

The following is an example of a CSV file for batch update.

31 1553-5/CXP9040776 Uen E1 | 2019-11-25

Resource Management

Table 17 Example of CSV File for Batch Update

deviceID MSISDN Exernal-ID

dg1364757868689 13898385460 -

dg1364757868690 - [email protected]

dg1364757868691 - -

Note: Leaving both MSISDN and External-ID empty means to remove the

identifier for the device.

5.2.4 Device Import

Devices can be batch imported using the CSV files. By default, a maximum of 1000 devices can be imported in one batch of a CSV file.

— The device entries per file can be configured as needed. To enlarge the upload size, configure the BATCH_DEVICES_MAX_NUM parameter in iot- provisioning-rest deployment.

— The time duration for device batch import depends on the capability of the deployment environment. To ensure the efficiency and reliability of the operation, you are advised to upload no more than 50,000 devices per run.

For details about the configuration for batch device import, refer to System Operation and Maintenance Guide>Partner Portal Configurations >Configure Batch Import Settings.

5.2.5 Device Data Export

On Partner Portal, data of multiple devices can be batch exported into a ZIP package. The data can include device names, IDs, certificates, and so on. The actual data exported varies with the device types. The devices can be filtered based on the following criteria:

— Device type

Exports data of devices associated with a specific device type.

— Manufacturer

Exports data of devices of a specific manufacturer.

— Device ID

Exports data of devices of specific device IDs.

— Device name

Exports data of devices whose names contain specific characters.

mailto:[email protected]

mailto:[email protected]

32 1553-5/CXP9040776 Uen E1 | 2019-11-25

Resource Management

The ZIP package contains CSV files with parameters of each device and certificate folders with all related X.509 certificates. A CSV file contains only one type of devices. The CVS file is chunked based on the limited size as configured. The default value is 100 device entries per file. If the target devices belong to multiple device types, multiple CSV files will be generated. By using the CSV files, the devices can be batch imported for migration or for other purposes.

For details about the parameters of each device, refer to the Import Devices GUI on Partner Portal.

5.2.6 Device Data Management

5.2.6.1 LwM2M Device Data Management

The Device Data Management function provided for a device created and associated with an LwM2M device type is specified by the OMA LwM2M object file uploaded when the device type is created. This function also enables developers to perform device management operations, including observe, read, write, and execute.

Multiple LwM2M object files can be uploaded to define multiple objects, for example, Device and LwM2M Software Management. Multiple object instances of an object, for example, software 1 and software 2 of LwM2M Software Management, are supported and can be displayed on the GUI.

When the device management operations are performed on a resource of an object instance, and this resource has multiple instances, the result of the selected resource instance can be returned and displayed on the GUI. For example, reading the available battery source of a device returns the selected source.

For details about the LwM2M objects, object instances, resources, and resource instances, refer to LwM2M Technical Specification.

5.2.6.2 MQTT and CoAP Device Data Management

The Device Data Management function is offered for MQTT and CoAP devices to view device messages.

The prerequisite for the Device Data Management function is that the corresponding topic permissions are enabled for a device type.

— MQTT topic permission for MQTT devices

— CoAP topic permission for CoAP devices

— All protocols topic permission for both MQTT and CoAP devices

The feature can be accessed with the following path:

http://www.openmobilealliance.org/release/LightweightM2M/V1_0_1-20170704-A/OMA-TS-LightweightM2M-V1_0_1-20170704-A.pdf

33 1553-5/CXP9040776 Uen E1 | 2019-11-25

Resource Management

Resources > Devices > {Device Name} > General > Device Info > Device Data View > View Messages

Device Data Management feature can be enabled by clicking the START button. When enabled, messages can be viewed with Time, Size, and Body.

5.2.7 Device Status Visualization

Partner Portal support visualizing traffic status of LwM2M devices and MQTT devices. On Partner Portal GUI, the device status is reflected by the value of the following field:

RESOURCES > DEVICES > General > Connection Status

The followings are all device status information according to different communication protocols:

— All Device

• Never Connected - The initial device status common to all types of devices.

— LwM2M Device

For LwM2M devices, the device status changes with operations performed on the device. The operations can be initiated by device or initiated by server. For status transition of LwM2M devices, see Status Transition of LwM2M Devices on page 34.

• Bootstrapped - When a device is bootstrapped via the Client Initiated Bootstrap mode.

• Registered - When a device is registered to the LwM2M Server.

• FOTA - When a firmware over the air (FOTA) operation is in progress.

• SOTA - When a software over the air (SOTA) operation is in progress.

• Rebooting - When the LwM2M Server initiates a reboot operation on a device.

Note: Before a device registers to the server again.

• Sleeping - When a registered device stops interacting with the LwM2M server for a period of time.

• Registration Expired - When the registration of a device is expired.

• De-registered - When a device is de-registered with the LwM2M Server.

— MQTT Device

34 1553-5/CXP9040776 Uen E1 | 2019-11-25

Resource Management

For MQTT devices, the device status changes with the connection status. For connection status transition of MQTT devices, see Status Transition of MQTT Devices on page 35.

• Connected - When a device is connected with the server.

• Disconnected - When a device is disconnected with the server.

— CoAP Device

• Communicated - When a device is communicating with the Server.

If a device is on-boarded with multiple communication protocols, types of device status for multiple protocols are exposed for the device. For example, a device on-boarded with the LwM2M and MQTT protocols can be MQTT Connected and LwM2M Registered at the same time.

5.2.7.1 Status Transition of LwM2M Devices

The following diagram illustrates the connection status transition for the LwM2M devices.

Figure 2 Connection Status Transition of a LwM2M Device

Note: The initial status of an on-boarded LwM2M device is Never Connected.

For details on different status of the LwM2M devices, see Device Status Visualization on page 33.

35 1553-5/CXP9040776 Uen E1 | 2019-11-25

Resource Management

5.2.7.2 Status Transition of MQTT Devices

The following diagram illustrates the connection status transition for the MQTT devices.

Figure 3 Connection Status Transition of a MQTT Device

For details on different status of the MQTT devices, see Device Status Visualization on page 33.

5.3 Device Job Management

Performing an operation on a group of target devices is a routine job for users. For example, a manufacturer needs to provide efficient and timely software updates for a group of devices and a partner needs to observe the battery level, free memory and other resources on a massive number of devices.

If a job performs an operation on multiple devices, the job is called a batch job. A batch job allows the partner to perform an operation on a single or a group of devices of a specified device type. The specified device type must support the LwM2M protocol. An administrator can implement a batch job on behalf of a partner.

Batch job management features are supported on Partner Portal GUI with the following paths:

— The Manage Device Jobs page accessed through Partner Portal GUI >

Resources > Device Jobs

• Create a batch job with Add Device Job .

• Check the list of batch jobs.

• Check the basic information of a batch job including the status, how many batch job item are failed, the job type, and the start time.

• Delete one or multiple batch jobs from the batch job list.

36 1553-5/CXP9040776 Uen E1 | 2019-11-25

Resource Management

— The Device Job Details page accessed through Partner Portal GUI > Resources > Device Jobs > {Batch Job Name}

• Check the detailed information of a batch job, including the summarized execution status of the batch job items, filtering criteria, filtered devices, job settings, and scheduling information.

• Check the list of batch job items of a batch job.

• Check the information of a batch job item, including the targeted device, the status, the error log if failed, and the last updated time .

— The Job Data page accessed through Partner Portal GUI > Resources > Device Jobs > {Batch Job Name} > {Device Name}

• Check the detailed information of a read or observation job, including the device resource values, job status, the last updated time, and the TTL (only applicable for observation jobs).

Creating a batch job involves the following four steps:

Partner Portal GUI > Resources > Device Jobs > Add Device Job

1. Specify the batch job name and type (LwM2M operation).

Each batch job supports only one specific LwM2M operation. Supported LwM2M operations include Software Installation, Software Management, Firmware Installation, Device Observation, Read, Write, and Execute. For detailed introduction about the LwM2M operations, see Supported Job Types on page 37.

2. Determine the target devices on which the LwM2M operation is performed.

The target devices of a batch job can be filtered by several criteria. For details of target device filtering, see Device Filtering in Batch Job on page 38.

3. Specify settings for the LwM2M operation.

The settings vary for different LwM2M operation types. For details about LwM2M operation settings, see Batch Operation Settings on page 39.

4. Specify schedule for the batch job execution.

Partner Portal supports to schedule batch job execution using specified periods and recurrent periods. Pacing and throttling settings are also supported. For details of batch job scheduling, see Batch Job Scheduling on page 48.

When creating a batch job, also consider the following aspects :

— A batch only applies to the devices of the specified device type that exist at the time when the job is created.

37 1553-5/CXP9040776 Uen E1 | 2019-11-25

Resource Management

— For devices added to the device types later, this batch does not prevail.

— The target devices for a batch must support the LwM2M protocol.

5.3.1 Supported Job Types

Each batch job supports one specific type of LwM2M operations to be performed on all target devices. Supported LwM2M operations for a batch job are as follows:

— Firmware installation

Firmware Over-The-Air (FOTA) is a technology with which the operating firmware of devices is wirelessly installed or updated by its manufacturer. Firmware installation enables FOTA-capable devices with efficient and timely firmware installation or update over the air.

Only one firmware version can exist for a device. A new version overwrites the existing one.

— Software installation

Software Over-The-Air (SOTA) is a technology with which the software of devices is wirelessly updated or managed by its manufacturer. Software installation allows SOTA-capable devices to download packages directly from the service provider for efficient and timely software installation or update over the air.

— Software management

Multiple software versions can coexist for devices. Thus, management functions, namely, enable, disable, and uninstall software of a specific version are available on Partner Portal. Software management allows manufacturers to provide efficient and timely software management for a single or multiple SOTA-capable target devices over the air. The following software management operations are supported:

— Enable software

— Disable software

— Uninstall software

— Device Observation

Observe is an operation defined in OMA Lightweight Machine to Machine Technical Specification. It allows the LwM2M Server to observe changes in resources on a single registered LwM2M device. Batch device observation allows the observation of resources within a group of devices. The observed resources can belong to one object instance or multiple object instances for one object or multiple objects. When value changes are available on

38 1553-5/CXP9040776 Uen E1 | 2019-11-25

Resource Management

observed devices, a partner can fetch the observation results for the observed devices.

A batch observation survives a device's re-registrations. The Observe message is automatically resent to a device immediately after any registration subsequent to the job creation if the job has not been explicitly canceled and the Time to Live (TTL) has not expired.

— Read

Read is an operation defined in OMA Lightweight Machine to Machine Technical Specification, which is used to access the values of the object instances, resources, and resource instances of an object on a single registered LwM2M device. Batch Read allows a partner developer to perform the Read operation on a selected group of registered LwM2M devices.

— Write

Write is an operation defined in OMA Lightweight Machine to Machine Technical Specification, which is used to change the values of the object instances, resources, and resource instances of an object on a single registered LwM2M device. Batch Write allows a partner developer to perform the Write operation on a selected group of registered LwM2M devices.

— Execute

Execute is an operation defined in OMA Lightweight Machine to Machine Technical Specification, which is used to initial actions on individual resource for a single registered LwM2M device. Batch Execute allows a partner developer to perform the Execute operation on a selected group of registered LwM2M devices.

5.3.2 Device Filtering in Batch Job

On Partner Portal, batch job can be created and scheduled on selected devices. The selection of target devices supports the following filtering criteria:

Note: The available filter criteria can be different among different batch job

operation types.

— (1)Target Device

One of the following must be selected:

— Specific Devices

— By Device Type

Note: This selection is only available for Software Installation and Software Management job types.

— Device IDs

39 1553-5/CXP9040776 Uen E1 | 2019-11-25

Resource Management

Search for target device whose device id equals to the input.

To search for multiple device IDs, use comma to separate multiple values.

— Installed Software and Software Versions

You can further select software and specify software versions. When

filtering with software versions, the operator can be = or !=.

— Resources

For LwM2M devices, you can also use one or more Resource values as the criteria for device filtering.

When filtering with Resource values, the data type of resource value can be string, integer, or datetime.

• If the resource value is string data type, the operator can be =, !=.

• If the resource value is integer data type, the operator can be =, !=, <, <=, >, >=.

• If the resource value is datetime data type, the operator can be <, <=, >, >=.

— Manufacturer

Search target device by selecting manufacturer options.

5.3.3 Batch Operation Settings

Each batch job performs one specific type of operations. The operation settings vary for different operation types. The following subsections describe the detailed operation settings for different operation types.

5.3.3.1 Firmware Installation

The parameters for the LwM2M operation Firmware Installation (FOTA) for a batch job are listed in the following table.

Note: Only one firmware version can exist for a device. A new version of

firmware overwrites the existing one.

40 1553-5/CXP9040776 Uen E1 | 2019-11-25

Resource Management

Table 18 Batch FOTA Settings

Parameter Description Mandatory (Yes/No)

Example Value

Firmware Package Specifies the firmware package to be updated on the FOTA-capable devices.

Two options are offered to specify the firmware package:

— Upload firmware package by selecting a zip file for the firmware package.

— Upload firmware package by specifying a URL pointing to the zip file of the firmware package.

Yes A package named 1.0.2.zi

p.

Firmware Version Name

Mandatory.

Specifies the version of the firmware package.

Yes 1.0.2

Release Notes Specifies the release notes of the package.

No -

5.3.3.2 Software Installation

The parameters for the LwM2M operation Software Installation for a batch job are listed in the following table.

Note: Multiple software, and single software with multiple versions, can

coexist for a device.

Table 19 Software Installation Settings


Example Value

Software Name Specifies name of the software to install on the target devices.

Yes MyMap

Software Version Specifies version of the software to install on the target devices. Semantic versioning

Yes 2.0.2

41 1553-5/CXP9040776 Uen E1 | 2019-11-25

Resource Management

Parameter Description Mandatory

(Yes/No) Example Value

rules need to be followed.

Software Package Specifies the software package to be updated on the SOTA-capable devices.

Two options are offered to specify the software package:

— Upload software package by selecting a zip file for the software package.

— Upload software package by specifying a URL pointing to the zip file of the software package.

Yes A package named 2.0.2.zip.

Release Notes Specifies the release notes of the package.

No -

5.3.3.3 Software Management

The parameters for the LwM2M operation Software Management for a batch job are listed in the following table.

Note: Multiple software, and single software with multiple versions, can

coexist for a device.

Table 20 Software Management Settings


Example Value

Action to taken Specifies the action to be performed on the selected software of the target devices.

Following actions are supported:

— Enable

Yes Disable

42 1553-5/CXP9040776 Uen E1 | 2019-11-25

Resource Management



— Disable

— Uninstall

Software Version Specifies version of the software to install on the target devices. Semantic versioning rules need to be followed.

Yes MyMap(2. 0.2)

5.3.3.4 Device Observation

Batch Device Observation allows the LwM2M Servers to observe resource changes on a group of registered LwM2M devices within the specified Time to Live (TTL).

Note: Objects, object instances, resources, resources instances must be

readable to support the batch Device Observation operations.

The parameters for the LwM2M operation Device Observation for a batch job are listed in the following table.

Table 21 Device Observation Settings


Example Value

Time to Live (TTL) Specifies the maximum observe duration, in seconds, for a device.

No 1200

Object Name Specifies the object to observe.

Yes Device (3)

Object Instances Specifies the object instances to observe.

— Any Instance: All object instances.

Specific Instances: One or multiple object instances. If there are multiple object instances, use comma to separate multiple Object Instance IDs.

Yes Specific Instances :

Object Instance IDs: 0, 1

Resources Specifies the resources to observe.

Yes Specific Resource s:

43 1553-5/CXP9040776 Uen E1 | 2019-11-25

Resource Management



— Any Resource: All resources.

— Specific Resources: One or multiple resources specified.

• For single-instance resource, specify resources to observe with Resource Name.

Resource Instance is not applicable for single-instance resources.

• For multiple- instance resource, specify resources with Resource Name and Resource Instance

If Resource Instance is left empty, the operation will be performed on all resource instances of the specified resource.

Resource Name: Battery Status (20); Resource Instance: 3, 4

Resource Name: Battery Level (9)

Note: The above table lists the parameters for an object. Click Add Object to add another object to read.

Batch Device Observation supports up to 10 targets for all objects by default. The targets for each object can be calculated with the following formula:

Targets for an object = Number of object instances * number of resources

To change the maximum targets of each device for a batch Device Observation job, modify the value of the CM key batch.max.targets. For instructions, refer to Partner Portal Configurations in System Operation and Maintenance Guide.

44 1553-5/CXP9040776 Uen E1 | 2019-11-25

Resource Management

5.3.3.5 Read

The parameters for the LwM2M operation Read for a batch job are listed in the following table.


readable to support the batch Read operations.

Table 22 Read Settings


Example Value

Object Name Specifies the object to read. Yes Device (3)

Object Instances Specifies the object instances to read.

— Any Instance: All object instances.

Specific Instances: One or multiple object instances. If there are multiple object instances, use comma to separate multiple Object Instance IDs.

Yes Specific Instances :

Object Instance IDs: 0, 1

Resources Specifies the resources to read.

— Any Resource: All resources.

— Specific Resources: One or multiple resources specified.

• For single-instance resource, specify resources to observe with Resource Name.


• For multiple- instance resource,

Yes Specific Resource s:

Resource Name: Battery Status (20); Resource Instance: 3, 4

Resource Name: Battery Level (9)

45 1553-5/CXP9040776 Uen E1 | 2019-11-25

Resource Management



specify resources with Resource Name and Resource Instance.

If Resource Instance is left empty, the operation will be performed on all resource instances of the specified resource.

Note: The above table lists the parameters for an object. Click Add Object to add another object to observe.

Batch Read supports up to 10 targets for all objects by default. The targets for each object can be calculated with the following formula:


To change the maximum targets of each device for a batch Read job, modify the value of the CM key batch.max.targets. For instructions, refer to Partner Portal Configurations in System Operation and Maintenance Guide.

5.3.3.6 Write

The parameters for the LwM2M operation Write for a batch job are listed in the following table.


writable to support the batch Write operations.

Table 23 Write Settings


Example Value

Write Mode Specifies the mechanism to change multiple Resources or an array of Resource Instances:

— Replace: replaces the Object Instance or the Resource(s) with the new value provided in the "Write" operation. When

Yes Replace

46 1553-5/CXP9040776 Uen E1 | 2019-11-25

Resource Management



the Resource is a Multiple- Instance Resource, the existing array of Resource Instances is replaced to the condition the LwM2M Client authorizes that operation.

— Partial Update: updates Resources provided in the new value and leaves other existing Resources unchanged. When the Resource is a Multiple- Instance Resource, the existing array of Resource Instances is updated meaning some Instances may be created or overwritten to the condition the LwM2M Client authorizes such operations. Deleting via Partial Update is not possible.

Object Name

Specifies the object to write. Yes Device (3)

Object Instance ID

Specifies the object instance to write. Yes 0

Resources Specifies one or multiple resources to write with specified values.

— For single-instance resource, specify resources to write with Resource Name and Value.


— For multiple-instance resource, specify resources with Resource Name, Resource Instance, and Value.

— For Custom Resources, specify resources to write with Resource Name , Operator, and Value.

Yes Current Time (13)

is a writable resource with a single resource instance.

Resource Name: Current Time (13);Valu e: 03/10/2 019 00:00

Note: The above table lists the parameters for an object. Click Add Object to add another object to write.

47 1553-5/CXP9040776 Uen E1 | 2019-11-25

Resource Management

Batch Write supports up to 10 targets for all objects by default. The targets for each object can be calculated with the following formula:


To change the maximum targets of each device for a batch Write job, modify the value of the CM key batch.max.targets. For instructions, refer to Partner Portal Configurations in System Operation and Maintenance Guide.

5.3.3.7 Execute

Batch Execute can be configured to initiate actions for a single resource from a single or multiple object instances of a single object. Batch execute are supported with arguments as specified in OMA LwM2M specification.

Note: — Resources must be executable to support the batch Execute

operations.

— Batch operation is limited to one resource per batch job to avoid conflicts that might be caused. For example, the Execute operation on the Reboot (4) resource of the Device (3) will conflict with the Execution operation on other resources.

The parameters for the LwM2M operation Execute for a batch job are listed in the following table.

Table 24 Execute Settings

Parameter Description Example Value

Object Name Specifies the object. LwM2M Server (1)

Object Instance IDs Specifies the object instances to execute.

Use comma to separate different object instance IDs.

0

Resource Name Specifies the resource to execute.

Disable (4)

Arguments Specifies the arguments of the Execute operation are expressed in Plain Text format (syntax below).

In using ABNF, the syntax of the arguments, and arguments list is given as follows:

1. 5 2. 2='10.3' 3. 7, 0=' https:// www.omaspecworks.o rg' 4. 0,1,2,3,4

http://www.omaspecworks.o/

48 1553-5/CXP9040776 Uen E1 | 2019-11-25

Resource Management

Parameter Description Example Value

arglist = arg* (","

arg) arg = DIGIT / DIGIT

"=" "" *CHAR"" DIGIT = "0" / "1" / "2" / "3"/ "4" / " 5" / "6" / "7" / "8

" / "9" CHAR = "!" / %x23-2 6 / %x28-5B / %x5D-

7E

5.3.4 Batch Job Scheduling

On Partner Portal, a batch can be created and scheduled for a selected group of devices. A partner is allowed to define multiple execution periods to run the individual jobs for a batch. The number of individual jobs executed in a period depends on the pacing and throttling parameters. The individual jobs that are not finished after a execution period are scheduled on subsequent execution periods.

Batch job scheduling involves the following steps:

1. Define the execution periods to run the batch.

See Execution Periods on page 48 for details of the execution period options and parameters.

2. Configure pacing and throttling of individual job launch during the defined execution periods.

See Pacing and Throttling on page 51 for details of the pacing and throttling parameters.

For details of the scheduling parameters, see the following tables.

5.3.4.1 Execution Periods

A partner is allowed to define the execution periods with one of the following schedule types:

— Periods: Define execution periods by specifying the start time and end time of

each period.

— Recurrence: Define execution periods by specifying recurrence in a daily, weekly, or monthly pattern.

For details of the execution period defining parameters, see the following tables. The parameters for the two schedule types are listed respectively

49 1553-5/CXP9040776 Uen E1 | 2019-11-25

Resource Management

Parameters for Defining Periods with Start and End Time

The following table lists the parameters for defining the execution periods by specifying the start time and end time of each period.

Table 25 Parameters for Defining Periods with Start and End Time

Configuration Item Description Mandatory (Yes/No)

Schedule Type

Periods This option allows you to define execution periods by specifying the start time and end time of each period.

Yes

Run Periods Start Specify the date and time of the moment when the batch starts processing (starts the launch of individual jobs).

Yes

End Specify the date and time of the moment when the batch stops processing (suspends the launch of individual jobs).

Note:

If end time is not specified for an execution period, Pacing > Even is not selectable.

No

Add Period You can define multiple execution periods by specifying start and end time for each period.

The individual jobs that are not finished after a execution period are scheduled on subsequent execution periods.

No

Parameters for Defining Periods with Recurrence

The following table lists the parameters for defining the execution periods by specifying recurrence in a daily, weekly, or monthly pattern.

Table 26 Parameters for Defining Periods with Recurrence

Configuration Item Description Mandatory (Yes/No)

Schedule Type

Recurrence This option allows you to define execution periods by specifying recurrence in a daily, weekly, or monthly pattern.

Yes

50 1553-5/CXP9040776 Uen E1 | 2019-11-25

Resource Management

Configuration Item Description Mandatory

(Yes/No)

Pattern Daily This option allows your to define the recurrence in a daily pattern.

If Daily is selected, also specify the number of interval days for the daily recurrence pattern. For example, Every 3 Days.

Yes

(1)

Weekly This option allows your to define the recurrence in a weekly pattern.

If Weekly is selected, also specify the number of interval weeks for the weekly recurrence pattern, and select particular days in a week for the occurrences. For example, you can define the execution period to occur on Sat and Sun in Every 2 Weeks.

Monthly This option allows your to define the recurrence in a monthly pattern.

If Monthly is selected, specify a particular day in a month for the monthly recurrence. For example, Day 25 of every month. You can also select The last day of every month instead of specifying a number for the day.

Time Period Start Specify the time of the moment when the batch starts processing (starts the launch of individual jobs) on the days of occurrence.

Yes

End Specify the time of the moment when the batch stops processing (suspends the launch of individual jobs) on the days of occurrence.

Yes

Start Date Specify the start date of the recurrence.

Yes

End End Date Specify the end date of the recurrence.

Yes

(2)

End After Specify the number of occurrences after which the recurrence is end. For example, End After 20 Occurrences.

(1) You must select one of the recurrence patterns.

(2) You must select one of the ways to determine when to end the recurrence.

51 1553-5/CXP9040776 Uen E1 | 2019-11-25

Resource Management

5.3.4.2 Pacing and Throttling

The following table lists the parameters for configuring pacing and throttling of individual job launch during the defined execution periods.

Table 27 Parameters for Pacing and Throttling Settings

Configuration Item

Description Mandatory (Yes/No)

Pacing This setting is used to specify the distribution of individual job launch across the defined execution periods. Two options are available:

— ASAP:

Individual jobs are launched as soon as possible subject to the throttling settings.

This is the default setting of pacing.

— Even:

The launch of individual jobs is evenly distributed within the execution periods.

Yes

(1)

Throttling This setting is used to control the maximum number of individual jobs to be launched in a specified throttling period. For example, maximum 100 requests within 1 minute.

By the default, the minimum value of the throttling period is 60 seconds.

Note:

Throttling is only applicable for ASAP pacing.

No

(1) You must select one of the pacing options.

5.3.5 Device Job Status

On Partner Portal GUI, you can query all device jobs that are associated with a device, and you can also query device jobs with several filter criteria.

Query Jobs by Device

You can query all associated device jobs of a device on Partner Portal GUI with the following path:

Resources > Devices > (Select the device) > General > Device Job Status

52 1553-5/CXP9040776 Uen E1 | 2019-11-25

Resource Management

Query Jobs by Filter Criteria

On Partner Portal Resources page, you can filter the device job list with several criteria, such as device id, job id, job type, job status, and job creation time. The GUI path is as follows:

Resources > Device Jobs > (Select the device job status)

The query result is sorted by job creation time.

By system level default settings, the maximum number of records can be shown in the query result is 200.

53 1553-5/CXP9040776 Uen E1 | 2019-11-25

API Access Management

6 API Access Management

API Access management is achieved by API keys and OAuth registration.

6.1 API Keys

An API key provides developers with the key ID and authentication token needed to access or request a specific API. One developer can have one or more API keys for different purposes. On Partner Portal, an API key can be created to obtain the access to an API with a usage plan specified. The use of the available API is subject to this usage plan.

An API key with a standard API usage plan can be successfully created without the approval of the administrator, while that with a customized API usage plan requires the approval of the administrator.

The following table lists the configuration items that are required when creating API Keys:

Table 28 Configuration Items for API Key Creation

Configuration Items Description

Key Name Specify a string which is used to identify an API key.

API Usage Plan Select the usage plan to be associated with the API key. All requests using this API key are metered and applied with the rate limits that are set in the associated usage plan. The usage plan is used to prevent abuse of the service. The API requests are blocked if they exceed the rate limits.

— Standard API Usage Plan The standard API usage plan is designed for the majority production, which applies predefined standard rate limits to each of the enabled API.

— Customized API Usage Plan You may customize the API rate limits on demand.

Enable API Access Select the APIs to enable access with the API key. For each selected API, the rate limits (Daily Requests and Requests/Second) are shown. You may change the rate limit settings if Customized API Usage Plan is selected for the API key.

After an API key is created, its status can be viewed on Partner Portal to check whether the API key is ready for use. The following table lists API key status for the administrator and developers.

Table 29 API Key Status for Administrators and Developers

User Status Description

Developer Active Indicates that the API key is ready for use because it is unblocked or approved for creation by the administrator.

Inactive Indicates that the API key is not ready for use and the following lists possible sub-status:

— Pending indicates that the API key creation is waiting for being processed by the administrator.

54 1553-5/CXP9040776 Uen E1 | 2019-11-25

API Access Management

User Status Description

— Blocked indicates that the API key is blocked by the administrator.

— Rejected indicates that the API key creation is rejected by the

administrator.

— Fail indicates that the API key fails to be created due to system errors.

— Processing indicates that the API key is being created.

Administrator Pending Indicates that the API key creation is waiting for processing.

Active Indicates that the API key creation is approved.

Rejected Indicates that the API key creation is rejected.

Blocked Indicates that the API key is blocked.

An API can relate to multiple API keys.

6.2 OAuth Registration

OAuth Registration needs to be created only when obtaining specific end user data requires end user authorization. Only data to be obtained by invoking APIs relating to the scopes specified during the OAuth Registration creation requires authorization. OAuth is an open standard for authorization, and is commonly used by Internet users to log in to third-party web sites through their Google, Facebook, or Twitter accounts, without worrying about their access credentials being compromised.

To use OAuth in the application, the application needs to be registered on Partner Portal to obtain a registration ID and a client secret that are used for the application development, for example, to obtain the OAuth access token by OAuth flow. Some OAuth Registration information can be modified and updated. After the update, the new configurations prevail.

The application OAuth registration in Partner Portal requires the following mandatory configuration items:

Table 30 OAuth Registration Configurations

Configuration Items Description

Application Type Select Web Application.

Application Name Shown to User Specify a string as the application name. The application name is presented with an authorization request.

Grant Type Select Client Credentials.

OAuth Scopes Select the user data that the application needs to access.

55 1553-5/CXP9040776 Uen E1 | 2019-11-25

API Directory

7 API Directory

API Directory shows the exposed APIs together with versioned API specification documents. All exposed APIs, either T-Mobile platform-provided APIs or new exposed APIs in each customized solution, can be published in API Directory. Developers can explore and try out the available exposed APIs listed in API Directory following instructions on Partner Portal.

56 1553-5/CXP9040776 Uen E1 | 2019-11-25

API Directory

8 API Dashboard

API Dashboard provides the function of displaying the monitored usage status of an API. With API Dashboard, developers can have a good command of the API usage, and system administrators can monitor APIs of all partners and developers.

The usage status can be viewed with a time span, and can be refreshed manually or automatically. The total number of requests, request rate, and number of successful responses are all listed, including the average and peak request rate. Additionally, the traffic (expressed in requests per second), error percentage to total requests, and median latency are also displayed.

57 1553-5/CXP9040776 Uen E1 | 2019-11-25

Device Dashboard

9 Device Dashboard

Device Dashboard provides the function of displaying the monitored status and traffic of devices. With Device Board, developers can have a good command of the belonging devices, and system administrators can monitor devices of all partners and developers.

The device status can be viewed according to protocols, and the device traffic can be viewed with different time span. The throughput of uplink and downlink message traffic is also displayed. The Device Dashboard page can be manually refreshed or automatically refreshed on a given interval.

58 1553-5/CXP9040776 Uen E1 | 2019-11-25

Device Dashboard

10 Device Client Examples

The device client development examples on Partner Portal help you to easily and quickly connect devices to the portal. The development examples include open-source libraries and developer guides with samples, so that you can build innovative IoT products or solutions on your choice of hardware platforms.

Partner Portal provides different kinds of device client development examples as follows:

— LwM2M device client examples:

• Java

The device client development for Java allows developers to write Java applications that access Partner Portal through LwM2M.

• C

The device client development for C allows developers to write C applications that access Partner Portal through LwM2M.

— MQTT device client examples:

• Embedded C

The device client example for Embedded C is a collection of C source files that can be used in embedded applications to securely connect to Partner Portal.

It includes transport clients, TLS implementations, and examples for their use. It is distributed as source code and is intended to be built into customer firmware along with application code, other libraries, and RTOS.

• Python

For details about IoT device client development for Python, access the website:

https://github.com/aws/aws-iot-device-sdk-arduino-yun

• NodeJS

The device client development for JavaScript allows developers to write JavaScript applications that access Partner Portal through MQTT over the WebSocket protocol. It can be used in Node.js environments and browser applications.

— CoAP device client examples:

https://github.com/aws/aws-iot-device-sdk-arduino-yun

59 1553-5/CXP9040776 Uen E1 | 2019-11-25

Device Client Examples

• CoAP Device

The device client development for CoAP allows developers to write applications that access Partner Portal through CoAP.

60 1553-5/CXP9040776 Uen E1 | 2019-11-25

Device Client Examples

11 Features Only for Administrators

This chapter describes the Partner Portal features that are only available for Administrators.

11.1 Partner Assignement

11.1.1 Assign Partners to Admin Users

A system administrator with the Manage Admin Users permission is allowed to assign partners to specific admin users for management.

Partners can be assigned to an admin user while the system administrator is creating or updating the admin user through the following paths:

— Administration > Account Manager > Admin Users > Add User > Partners

— Administration > Account Manager > Admin Users > {Admin User} > Edit User > Partners

An admin user can be configured by the system administrator to manage a subset of partners. When a partner is assigned to or unassigned from an admin user, both the partner and the admin user receive email notifications.

Note: — One partner can be assigned to one or multiple admin users.

— The Manage Admin Users permission is required for a system administrator for partner assignment.

11.1.2 View Associated Admin Users of a Partner

When a partner is assigned to an admin user, the admin user can view the associated admins of the partner through the following path:

Home > Partners and Developers > {Partner} > Basic Info

All admin users that have the permission to manage the partner is displayed in the result list. The information of the admin users including the user name, email address, and telephone number of the admin users is displayed.

Note: The Manage Admin Users permission is required for a system administrator to view the list of admin users assigned to manage a partner.

61 1553-5/CXP9040776 Uen E1 | 2019-11-25

Features Only for Administrators

11.2 LwM2M Server and ACL Management

One LwM2M device may have multiple Internal LwM2M Servers. The system is able to choose the appropriate LwM2M Server endpoint to downlink the request according to the associated LwM2M Servers and the Access Control List (ACL) defined on the device type. For each operation on the LwM2M device object instance, the system checks the server if it has permission to do the operation.

System administrator can operate on behalf of partner to configure the LwM2M Servers and ACL on the device type for partners. On the Device Type Details page of Partner Portal GUI, single or multiple LwM2M servers can be configured:

— Single Server

Full operating permissions are assigned to the single LwM2M Server to access all object instances of this device type. By default, the default Internal LwM2M Server is associated with each device type. System administrator may change the associated LwM2M Server.

— Multiple Servers

If multiple LwM2M Servers are assigned to the device type, the permissions of the LwM2M Servers must be defined for each object of this device type.

For instructions on how to access the configuration page, see Configure LwM2M Servers and ACL on Device Type on page 77.

11.3 LwM2M Server Configuration

LwM2M Servers can be configured by system administrator on Partner Portal. The

mandatory configuration items are listed as follows:

Table 31 Mandatory Configuration Items

Configuration Item Description

Server Name The name of a LwM2M Server.

Need Bootstrap Write Indicates whether the LwM2M Server configuration needs to be written to device during Bootstrap phase. If the server type is Internal, Need Bootstrap Write must be set to true.

Lifetime The lifetime of the registration in seconds.

Default Min Period The minimum time (in seconds) that the LwM2M device must wait between two notifications.

Default Max Period The maximum time (in seconds) that the LwM2M device may wait between two notifications.

Disable Timeout The timeout period (in seconds) to disable the server. After this period, the LwM2M device must perform registration process to the server.

Notification Storing When Disabled or Offline

Indicates whether to enable Notification Storing when the LwM2M device is disabled or offline. The value is either true or false. The default value is true.

Binding Defines the transport binding configured for the LwM2M device.

62 1553-5/CXP9040776 Uen E1 | 2019-11-25


For instructions on how to access the configuration items, see Configure LwM2M Servers and ACL on Device Type on page 77.

11.4 Enable API Access for a Partner

The prerequisite for a partner to call an API specification is that the partner is enabled the access to the API. System Administrator is able to enable API access for a partner.

For System Administrator, to enable API access for a partner:

Steps

1. Access https://<host:port> and log on to the system with the manager

account.

The host and port mentioned in URL are the ones for the Kubernetes service iot-proxy.

2. Access the Partner Info page by clicking Partners and Developers > Partners > {Partner Name}.

Result: The Partner Info page for the specified partner opens.

3. Click APIs > ENABLE API ACCESS.

Result: The ADD API ACCESS dialog box opens.

4. Select APIs and click ADD.

5. Input DAILY REQUESTS and REQUESTS/SECOND for each selected API. Note:

The same value can be set to all selected APIs at the same time.

6. Click Save.

Results

The selected APIs are enabled for the specified partner with the limits of total daily requests and requests per second.

11.5 Approve API Key Creation

As the API key is created with a customized SLA specified, the approval of System Administrator is required. The API key is not available and ready for use until its creation is approved.

For System Administrator, to approve the pending API key creation application, perform the following:

63 1553-5/CXP9040776 Uen E1 | 2019-11-25


Steps


account.


2. At the right side of the home page, click API Keys.

Result: The API KEYS page opens.

3. Click PENDING.

Result: A list of API keys waiting for processing are displayed.

4. Select the API key whose creation you want to approve and click APPROVE on the top of the list.

Result: The APPROVE dialog box is displayed.

5. Click APPROVE.

Result: The API key whose creation you have approved is displayed in the list of active API keys.

11.6 Block or Unblock an API Key

System Administrator is able to block any active API key and unblock any blocked API key. Once the API key is blocked, the application equipped with the API key cannot access the API any more unless System Administrator unblocks it later.

For System Administrator, to block an API key, perform the following:

Steps


account.


2. At the right side of the home page, click API Keys.

Result: The API KEYS page opens.

3. Click ACTIVE.

Result: A list of active API keys are displayed.

64 1553-5/CXP9040776 Uen E1 | 2019-11-25


4. Select the API key that you want to block and click BLOCK on the top of the list.

Result: The BLOCK dialog box is displayed.

5. Click BLOCK.

Result: The API key you have blocked is displayed in the list of blocked API keys.

To unblock an API key, click BLOCKED, select the API key, and click UNBLOCK. The procedure is similar to that of blocking an API key.

11.7 Partner Topic Permission Management

Topic Permissions are the pages on Partner Portal for a system administrator to view and manage the policies defining which partners can access what topics. For more information about Topic Permission, refer to Partner Topic Permission Management in IoT Feature Description. The default topic types include All protocols, CoAP, LwM2M, LwM2M Events, MQTT, and NIDD.

Partner Topic Permission Management feature allows a system administrator to do the following:

— Enable, disable topic permissions for a partner.

— Define the partition number of a topic enabled by the system administrator for a partner. The default value is two, and the maximum is ten.

— Define the maximum MQTT clients for a partner.

For the displayed names and prefixes of topic types, default and maximum values of MQTT client and partition, and topic permission requirement before approval, the configurations are available. For instructions, refer to Configure Partner Topic Permission Settings in System Operation and Maintenance Guide.

65 1553-5/CXP9040776 Uen E1 | 2019-11-25

Example Scenarios

12 Example Scenarios

12.1 On-Board Devices on Partner Portal

There are different cases for the southbound devices to communicate with the northbound applications. Except the cases when SCEF is involved, Dispatcher always plays a role in the device communication.

The procedures of on-boarding devices on Partner Portal to communicate with the northbound applications are similar. In this section, the following examples are provided:

— On-boarding a LwM2M and MQTT device instance

— On-boarding a CoAP device instance

Prerequisites

— CDM and Dispatcher have been integrated in terms of CoAP and LwM2M functions.

— Prepared developer account, see Prepare Accounts on page 65.

Steps

1. Prepare device types. For details, see Prepare Device Types on page 70.

2. On-board a LwM2M and MQTT device instance. For details, see On-Board LwM2M and MQTT Device Instance on page 72.

3. On-board a CoAP device instance. For details, see On-Board CoAP Device Instance on page 73.

12.1.1 Prepare Accounts

A system administrator can access and manage resources of developers. That is to say, an administrator can perform operations on behalf of a developer. For details about roles and permissions, see Partner and User Management on page 7 .

Steps

1. Prepare the administration account. For details, see Prepare Administration Account.

66 1553-5/CXP9040776 Uen E1 | 2019-11-25

Example Scenarios

2. Administrator creates an account for Partner on Partner Portal. For details, see Prepare Partner Account.

3. Partner creates an account for Developer on Partner Portal. For details, see Prepare Developer Account.

12.1.1.1 Prepare Administration Account

After system installation, the following default administration account is provided in Account Manager.

Username: manager

Password: manager

To change the default password of manager account for security reason, perform the following:

Steps

1. Access https://<host:port>/account-manager/login and log on to system with manager account.


2. Click Administration icon. The

Admin Users GUI opens.

3. On the upper-right corner of GUI, click the current user manager and select My Account.

4. Click Change Password and set a new password.

5. Click Save.

To create other administration accounts, click Add User in the Admin Users GUI, and fill in related fields and assign one or more administration roles to te created administration account. A role must be created before an administration account is created. For how to create a system administrator, see Create Administration Account.

If any of these administration accounts are locked, contact the platform administrator for further help.

12.1.1.1.1 Create Administration Account

After the system is installed, a default system administrator account is provided as follows:

67 1553-5/CXP9040776 Uen E1 | 2019-11-25

Example Scenarios

Username: manager

Password: manager

The default system administrator has all permissions available and can create multiple system administrator accounts with different roles.

To create a system administrator account, perform the following:

Steps

1. Access https://<host>:<port>/account-manager/login and log on to the system with the manager account.


2. On the start page, click Administration.

Result: The Admin Users GUI is displayed.

3. Select Admin Users & Roles > Roles > CREATE NEW ROLE.

Result: The Create New Role page is displayed.

4. Under the Basic Information area, enter values for the fields as prompted.

5. Under the Permission Information area, select permissions of OEM Admin, Partner Portal Admin, and Partner Portal Admin (On-behalf Permissions)

For details about the permissions, refer to Roles and Permissions of System Administrators in Partner Portal Tutorial.

6. Click CREATE.

Result: The Roles tab page is displayed and the created role is in the list.

7. On the Admin Users tab page, click ADD USER.

8. Under the Basic Information area, enter values for the fields as prompted.

9. Under the Role Information area, select the created role in the Available Roles box, and then click the < icon.

Result: The selected role is displayed in the left Assigned Roles box.

Note: More than one role can be assigned to one system administrator.

10. Click ADD.

Result: The created user is displayed on the Admin Users tab page.

68 1553-5/CXP9040776 Uen E1 | 2019-11-25

Example Scenarios

12.1.1.2 Prepare Partner Account

A partner is a tenant that is associated with a contact person and specified APIs for access. A partner is usually an organization, such as a company that has many developers. A contact person is a special user of a partner, acting as a partner administrator that manages developers of this partner. A partner has only one contact person. By default, a contact person has all permissions available on Partner Portal. There are two ways of creating a partner account as follows:

— The administrator creates a partner account and approves it.

— A partner applies for an account and then the administrator approves the application.

This user guide uses the first method, which is the common scenario, as an example to describe how to create a partner account.

Prerequisites

The Administrator account has been prepared and is ready for use.

Steps

As for the administrator, to create a partner account, perform the following:

1. Access https://<host:port> and log on to the system with the prepared administration account.


2. Click Partners and Developers.

Result: The Partners and Developers page is displayed.

3. On the page that is displayed, click Add Partner.

Result: The Add Partner page is displayed.

4. On the page that is displayed, enter information.

5. Click ADD PARTNER, or ADD PARTNER, GO TO EDIT TOPIC PERMISSION.

Note: Topic permission enablement is the prerequisite to activate a partner account. If want to enable the topic permissions later, click ADD PARTNER and move to Step 6.

Result:

— a. A confirmation email: notifies the Contact Person that the partner account application has been submitted.

69 1553-5/CXP9040776 Uen E1 | 2019-11-25

Example Scenarios

b. A notification email: informs the Contact Person that the account is created successfully. The username and password are also provided for the contact person to log in to Partner Portal.

— If click ADD PARTNER:

The created partner is listed on Partner and Developers page. And the status is PENDING.

— If click ADD PARTNER, GO TO EDIT TOPIC PERMISSION：

Topic Permissions section on PARTNER INFO page is displayed.

6. (Optional) Click the corresponding partner name in blue on Partners and Developers.

Result: Topic Permissions section on PARTNER INFO page is displayed.

7. Click EDIT on Topic Permissions.

Result: The topic list is displayed.

8. Enable the topic permissions for the partner, save the changes, and click APPROVE.

Note: Topic permissions are recommended to be well-planned before on- boarding a partner, and frequent update is not recommended. Reasons are as follows:

— Dispatcher loads topic permissions periodically into memory. Thus, permission update does not take effect immediately.

— Permission update does not affect the connected clients, or the existing subscriptions.

Result: The status of the partner on Partners and Developers is ACTIVATED.

12.1.1.3 Prepare Developer Account

A developer is the user of Partner Portal and can be created in the following ways:

— The contact person of a partner creates a developer account.

— The administrator creates a developer account.

— The developer registers with self-service.

This user guide uses the first method, which is the common scenario, as an example to describe how to create a developer account.

70 1553-5/CXP9040776 Uen E1 | 2019-11-25

Example Scenarios

Prerequisites

A partner account has been prepared and is ready for use.

Steps

As for the contact person of a partner, to create a developer account, perform the following:

1. Access https://<host:port> and log on to the system as the contact person of the prepared partner.


2. In the upper right corner of the home page, click the arrow icon next to the account name and choose My Company from the drop-down list.

Result: The MY COMPANY page is displayed.

3. Choose Roles > ADD ROLE.

Result: The ADD ROLE dialog box is displayed.

4. Enter the role name, select all device and device type permissions, and click ADD.

Result: The role is created successfully.

5. Choose Users > ADD USER.

Result: The ADD USER dialog box is displayed.

6. In the dialog box, enter information as prompted , select the created role, and click ADD.

Result: The created developer account is displayed in the user list. Two emails are sent to the developer:

— An email that welcomes the developer.

— An email that informs the developer of the account name and password.

12.1.2 Prepare Device Types

A device must be associated with a device type. Before the creation or batch import of devices, a device type needs to be created.

1. Prepare a device type that supports the MQTT and LwM2M protocols. For

details, see Prepare MQTT and LwM2M Device Type on page 71.

71 1553-5/CXP9040776 Uen E1 | 2019-11-25

Example Scenarios

2. Prepare a device type that supports the CoAP protocol. For details, see Prepare CoAP Device Type on page 71.

12.1.2.1 Prepare MQTT and LwM2M Device Type

Before creating a device type, prepare the developer account. For details, see Prepare Developer Account on page 69.

Developer creates the MQTT and LwM2M device type on Partner Portal with the following field settings.

Input Field Name Example Value

Device Type Name LwM2M-MQTT-Type

Protocols MQTT and LwM2M

Manufacturer OUI

00:01:EC

MQTT Specific Parameters

MQTT Data Object

JSON

— Sensor: GPS

— Sensor Resource: Latitude

— Type: Number

LwM2M Specific Parameters

LwM2M Delivery Mechanism

IP data

LwM2M Data Object

Select File... > Device.xml

Note: Upload the OMA LwM2M definition XML file of ObjectID 3 for this device type. The file can be downloaded from the link provided in the Data Object area on Partner Portal.

LwM2M Data Formats

TLV

For details on configurations of a device type, see Device Type Management on page 12.

12.1.2.2 Prepare CoAP Device Type


Device Type Name CoAP-Type

Protocols CoAP

Protocol Delivery Mechanism IP data Specific

CoAP Data Object JSON (Undefined Object) Paramet ers Callback

Paramet Applicati on Server

http://partnerportal:3000

ers Callback URL

72 1553-5/CXP9040776 Uen E1 | 2019-11-25

Example Scenarios


Security No Security

For details on configurations of a device type, see Device Type Management on page 12.

12.1.3 On-Board LwM2M and MQTT Device Instance

To on-board the device instance on Partner Portal:

Steps

1. Developer creates a LwM2M and MQTT device instance on Partner Portal with the following field settings.


Device Name LwM2M-MQTT-Device

Device ID dg2a3e983d0b7fe2qeeycw6esw1h

Note:

The value of this parameter can be automatically generated by the system or user-defined. This example value is automatically generated by the system.

Device Type Select the created LwM2M and MQTT device type LwM2M-MQTT-Type.

MQTT Security X.509 certificate: Automatically generate X.509 certificate

LwM2M

Security

Bootstrap Request

Yes, enable client initiated bootstrap

Bootstrap Security

PSK: Input Hex or Text Code: Ax72Ya

LwM2M Data Security

RPK: Automatically generate RPK

Result: The LwM2M and MQTT device instance is created successfully. The creation outputs are displayed.

2. Developer records the following outputs.

Output Field Name Example Value

LwM2M Security Bootstrap Security Identity dg3bf23f1541093sl3xvvvd7y2f

Password Ax72Ya

Note:

The value is the pre-shared key (PSK).

LwM2M Server Security

Public key MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcD QgAEHy8vIv08Fbv/bYzO +koZy87RoOElBa22Lm7rrwOAqZ4jrjJI VVfUpqQo61tNBPmTRgCzMhYARTJ0jtme lsYroQ==

Public key MEECAQAwEwYHKoZIzj0CAQYIKoZIzj0D AQcEJzAlAgEBBCCODoukpyJNQFzrysc3 eqHUtlr2dxx4Ee3vdR9eqoUo0Q==

Bootstrap Server Endpoint coap://10.175.190.132:5583

73 1553-5/CXP9040776 Uen E1 | 2019-11-25

Example Scenarios


LwM2M Server Endpoint coap://10.175.190.132:5683

MQTT Security Certificate dg21b90a67c5024t4vposlpwq5h_cert _MQTT

Note:

The value is the name of the cert package. The package needs to be downloaded to obtain the certificates and private key.

MQTT Publish Topic json/devicedata/P-20000oynK2V

MQTT Subscribe Topic json/P-20000oynK2V/devicedata

MQTT Server Endpoint mqtts://10.175.190.137:1883

12.1.4 On-Board CoAP Device Instance

To on-board a CoAP device instance on Partner Portal:

Steps

1. Developer creates a CoAP device instance on Partner Portal with the following field settings.


Device Name COAP-Device

Device ID dg2a3e983d0b7fe2qeeycw62gioh

Note:

The value of this parameter can be automatically generated by the system or user-defined. This example value is automatically generated by the system.

Device Type Select the created CoAP device type CoAP-Type.

CoAP Data Security PSK:

— Code Length: 8

Note: The code length ranges from 1 to 256 characters.

— Input Hex or Text Code: Specify Code Length first and then click GENERATE TEXT CODE. An example value is v%*Kb:VI.

Note: The code format can also be a hexadecimal string. In such a

case, manually input the string starting with 0x.

Result: The CoAP device instance is created successfully. The creation outputs are displayed.

2. Developer records the following output.


Identity dg3be62c0b406401h7lwcob4iqev

Password v%*Kb:VI

CoAP Server Endpoint coap://10.172.32.107:5685

74 1553-5/CXP9040776 Uen E1 | 2019-11-25

Example Scenarios

12.2 Update Devices on Partner Portal

A device must be associated with a device type. A device is defined by both configurations of a device and configurations of its associated device type.

Partner users with the permissions of Update Devices and Update Device Types are allowed to update on-boarded devices and the associated device type on Partner Portal. To update a device supporting only the CoAP protocol to support both the CoAP and LwM2M protocols:

Prerequisites

— A partner user with the permissions of Update Devices and Update Device Types. For details, see Prepare Accounts on page 65.

— A prepared device type. For details, see Prepare CoAP Device Type on page 71.

— A prepared device associated with the device type. For details, see On-Board CoAP Device Instance on page 73.

Steps

1. Log on Partner Portal with the account of a partner user with the permissions of Update Devices and Update Device Types.

2. Click Home > Resources > Device Types, and click the CoAP-Type device type for details.

3. Click Action > Update Details on the details page to update the configurations for the device type.

4. Update the CoAP-Type device type with the following configurations:

Configuration Item New Value Original Value

Device Type Name CoAP-LwM2MW-Type CoAP-Type

Protocols CoAP and LwM2M CoAP

LwM2M Specific Parameters LwM2M Delivery Mechanism

IP data N/A

LwM2M Data Object

Select File... > Device.xml N/A

LwM2M Data Formats

TLV N/A

For configurations that are editable at the device type level, see Device Type Update on page 18.

For the original configurations of the device type CoAP-Type, see Prepare CoAP Device Type on page 71.

75 1553-5/CXP9040776 Uen E1 | 2019-11-25

Example Scenarios

5. Update the configurations to the device type by clicking the Update button at the bottom of the Update page.

The updated configuration will be automatically applied to newly created devices associated with the device type. For the existing devices, changes on the device type need to be applied to the devices manually.

6. Click Home > Resources > Devices, and click the CoAP-Device device for details.

7. Click Action > Update Details on the details page for the device to update the configurations for the device.

8. Apply changes on the associated device type to the device by clicking the Apply Changes button.

Device Type of the device changes from CoAP-Device to CoAP-LwM2MW- Type. LwM2M specific settings display on the Update page for the device after manually apply the changes to the device type.

9. Continue to update the device CoAP-Device with the following configurations:

Configuration Item New Value Original Value

Device Name CoAP-LwM2MW-Device CoAP-Device

LwM2M Specific Parameters Bootstrap Request

Yes, enable client initiated bootstrap

N/A

Bootstrap Security

PSK

Input Hex or Text Code: Ax72Ya

N/A

LwM2M Data Object

RPK: Automatically generate raw public keys.

N/A

10. Update the configurations to the device by clicking the Update button at the bottom of the Update page.

For configurations that are editable at the device level, see Device Update on page 28.

For the original configurations of the device type CoAP-Device, see On- Board CoAP Device Instance on page 73.

Results

The device is successfully updated to support both the CoAP and LwM2M protocols.

12.3 Create FOTA Job for LwM2M Device

To create a FOTA job on Partner Portal GUI, do the following:

76 1553-5/CXP9040776 Uen E1 | 2019-11-25

Example Scenarios

Prerequisites

— Developer already has a thorough understanding of FOTA job.

— The LwM2M devices have been on-boarded and can communicate with CDM properly.

— A firmware package of a new firmware version is available and ready for use.

Steps

1. On Partner Portal, Developer creates a firmware installation job for LwM2M devices in one batch with the following field settings.

Table 32 Job Info & Target Device(s)

Field Operation and Example Value

Job Name Enter the job name manually. For example, Firmware C20180830

Job Type Select Firmware Installation from drop-down list.

Target Device Select Batch devices

Select Devices Select By Device Type, and then select the desired device type from the drop- down list.

2. Click Next and fill in with the following field settings:

Table 33 Firmware Installation

3. Click Start Job.

Result: A FOTA update process for LwM2M devices is triggered:

a. Partner Portal provisions the new firmware package to CDM.

b. Partner Portal creates a FOTA update job in CDM for each target LwM2M device.

c. CDM performs FOTA update on each LwM2M device.

d. LwM2M devices download the firmware package from CDM and install the package.

e. The LwM2M devices notify CDM that all the FOTA update jobs are implemented.

Field Operation and Example Value

Firmware Package Select Upload firmware package by selecting file

Firmware Version Name Enter the version name manually. The value is a string and must be unique for a LwM2M device type. For example, 1.2.0

Release Notes Enter the notes manually. For example, For cars only.

77 1553-5/CXP9040776 Uen E1 | 2019-11-25

Example Scenarios

4. On the DEVICE JOBS tab page of Partner Portal, Developer checks the firmware installation job status .

12.4 Configure LwM2M Servers and ACL on Device Type

This section provides a brief instructions on how to configure LwM2M Servers and ACL on device types that belong to a specific partner.

Prerequisites

The system administrator must have the Update LwM2M Server Configuration permission (one of the on-behalf device type permissions).

Steps

1. Log in to Partner Portal as a system administrator.

2. Operate on behalf of the partner.

3. Click Resources > Device Types, and then click the device type on which you want to configure LwM2M Servers and ACL.

Result: The device type information is shown on the right.

4. Click ACTION > View Details.

Result: The Device Type Details page is shown.

5. Click Edit in the LwM2M section.

6. Change the configurations:

— Select Single Server and choose the LwM2M Server from the drop-down list.

Result: The selected LwM2M Server is displayed in the sever information table.

— Select Multiple Servers and click the pencil icon for each object to assign permissions for the LwM2M Servers.

Result: The LwM2M Servers with assigned permissions are displayed in the object table. The selected LwM2M Servers are displayed in the server information table.

7. To change the LwM2M Server configuration, click the pencil icon for the LwM2M server, and update the configuration items as prompted. For details of the configuration items, see LwM2M Server Configuration on page 61.

Result: The configuration of selected LwM2M server is changed.

78 1553-5/CXP9040776 Uen E1 | 2019-11-25

Example Scenarios

8. Click Save to save the changes.

12.5 Getting Started with API Access

This section describes how to obtain API Access to an API exposed on Partner Portal, so that you can allow an application to access the desired end user data by invoking this API.

To obtain API Access, perform the following:

Steps

1. Obtain an API key on Partner Portal, see Create an API Key on page 78.

2. Enable the application to call APIs.

OAuth Registration needs to be created only when obtaining specific end user data requires end user authorization.

— If end user authorization is required, enable the application to call APIs with OAuth. See Call APIs with OAuth Enabled on page 79.

— If end user authorization is not required, enable the application to call APIs without OAuth. See Call APIs without OAuth on page 80.

12.5.1 Create an API Key

For developers, to obtain an API key on Partner Portal, perform the following:

Steps

1. Access https://<Partner Portal host> and log in to the system with a developer account.

2. Click API KEYS to enter the API KEYS page.

3. Create an API key for the API that you want to invoke in your application.

4. (Optional) Wait for the API key creation approval of the administrator.

Note: Approval is required only when you select a customized usage plan during API key creation. For details about API keys, see API Keys on page 53.

5. Check the API key status on the API KEYS page.

Result: The Active status indicate that the API key is created successfully.

79 1553-5/CXP9040776 Uen E1 | 2019-11-25

Example Scenarios

Note: If you select a customized SLA, the API key status is Pending at first, and then changes to Active after System Administrator approves the creation. For details about how System Administrator approves API key creation, see Approve API Key Creation on page 62.

12.5.2 Call APIs with OAuth Enabled


If end user authorization is required, perform the following to enable the application to call APIs with OAuth:

Prerequisites

— An API key is created for the API that you want to invoke in your application. For instructions, see Create an API Key on page 78.

Steps

1. Click OAUTH REGISTRATION to enter the OAUTH REGISTRATION page.

2. Register an application for OAuth with the OAuth scopes of the desired API.

Result: The application is successfully registered and the registration ID and client secret are displayed on the registration success page.

3. Get basic authentication by using Base64 to encode <registration ID>:<client secret.

For example, YXBwNmM0OGJlMGExZTliYnFlMWx0MzN2OTZqbDo4OWI4NWE2YTQ1OWQ0NmVmYj

g1YTZhNDU5ZGY2ZWZjZA==.

4. Copy the basic authentication and OAuth scopes to Authorization: Basic and grant_type=client_credentials&scope=, respectively in the POST request and send the POST request to obtain the OAuth access token.

Note: You can copy all or any of the OAuth scopes that you specified in Step 2.

The following is an example request:

Result: The OAuth access token is displayed after access_token in the response. The following is an example response:

200 OK Content-Type: application/json

80 1553-5/CXP9040776 Uen E1 | 2019-11-25

Example Scenarios

expires_in indicates that the OAuth access token expires in 43200 seconds.

5. Go to the API KEYS page and obtain the key ID of the created API key.

6. Copy the value of access_token and the key ID to Authorization: Bearer and AccessKey, respectively in the GET request and send the GET request to invoke the API with OAuth enabled.

The following is an example request:

If the OAuth access token expires before you invoke the API, you can refresh the OAuth access token by sending the POST request. The following is an example request:

→

The value after Authorization: Basic is the Base64 encoded basic authentication and the value of refresh_token is the expired OAuth access token.

Then, a response similar to the previous example response is returned. The value of access_token is the new OAuth access token. Invoke the API with the API key ID and new OAuth access token by sending the GET request shown in the previous example GET request.

12.5.3 Call APIs without OAuth


If end user authorization is not required, perform the following to enable the application to call APIs without OAuth:

Cache-Control: no-store Pragma: no-cache

{ "access_token":"M7DojmmHJv9JAKBvveQN", "token_type":"Bearer", "scope":"NASA" "expires_in":43200,

}

GET /proxy/hub/neo/rest/v1/neo/browse HTTP/1.1 Host: scs.pdulab.sh.cn.ao.ericsson.se Authorization: Bearer M7DojmmHJv9JAKBvveQN AccessKey: acs1371a43f7a6d41somxyxslkm01

POST /oauth2-api/p/v1/token HTTP/1.1 Host: scs.pdulab.sh.cn.ao.ericsson.se Content-Type: application/x-www-form-urlencoded Authorization: Basic YXBwNmM0OGJlMGExZTliYnFlMWx0MzN2OTZqbDo4OWI4NWE2YTQ1OWQ 0NmVmYjg1YTZhNDU5ZGY2ZWZjZA==

grant_type=refresh_token& refresh_token=M7DojmmHJv9JAKBvveQN

81 1553-5/CXP9040776 Uen E1 | 2019-11-25

Example Scenarios

Prerequisites

An API key is created for the API that you want to invoke in your application. For instructions, see Create an API Key on page 78.

Steps

1. Click API KEYS to enter the API KEYS page.

2. Click the created API Key.

Result: The Authentication Tokenof the API Key is displayed on the page.

3. Copy the authentication token of the API key to Authorization: Basic in the GET request, and send the request to invoke the API without OAuth enabled.

The following is an example of the request:

→

12.6 Getting Started with a Real Device

Partner Portal provides resource management for developers and System Integrators. Users can get started with Partner Portal through a real device, for example, simple humidity and temperature sensor. Users can create a device type and connect the device after a device software client is developed. The device type is similar to a data collection model. By doing so, device data, including humidity and temperature, can be collected.

This document uses Raspberry Pi as an example to explain the detailed procedure. For more information, see Getting Started with Raspberry Pi.

12.6.1 Verified Device

Raspberry Pi 3 model B is verified to be integrated with Partner Portal.

12.6.1.1 Raspberry Pi 3 Model B

The Raspberry Pi is just the credit-card sized computer. It is capable of many of the things that your desktop PC does, such as spreadsheets, word-processing, and playing high-definition videos and games. It can run several flavors of Linux (and even Windows 10 free-of-charge) and is being used to teach kids all over the world how to program.

Raspberry Pi 3 Model B boasts improved performance, connectivity, and power management with a 64-bit CPU and on-board Wi-Fi and Bluetooth.

GET /proxy/hub/neo/rest/v1/neo/browse HTTP/1.1 Host: scs.pdulab.sh.cn.ao.ericsson.se Authorization: Basic YWNzZjgyYmJjYTk3NTYydWJyZTYyYmYxampsOjY1YzYzNzc3ZWJkODQ xN2Y4NjM3NzdlYmQ4MzE3ZjU0

82 1553-5/CXP9040776 Uen E1 | 2019-11-25

Example Scenarios

For details about Raspberry Pi, visit the Raspberry Pi official website:

https://www.raspberrypi.org/

Figure 4 Raspberry Pi 1

Figure 5 Raspberry Pi 2

The specifications of Raspberry Pi 3 Model B are as follows:

— Quad core 1.2 GHz Broadcom BCM2837 CPU (64-bit ARM Cortex A53)

— 1 GB RAM

— BCM43143 Wi-Fi (802.11n)

https://www.raspberrypi.org/

83 1553-5/CXP9040776 Uen E1 | 2019-11-25

Example Scenarios

— Bluetooth Low Energy (BLE)

— 40 pin GPIO

— 4x USB 2 ports

— CSI camera port

— DSI display port

— MicroSD card slot

— HDMI

— 4 pole stereo and composite video port

— Upgraded Switched power source up to 2.4 A

12.6.1.1.1 Additional Accessories You May Require

You cannot do anything with the board unless you combine it with other accessories.

You may require the following additional accessories:

— Suitable power adapter

— Ethernet cable

— Micro SD card with SD adapter

In the document, the following peripherals are used as the devices to be integrated with Partner Portal.

— Buzzer

— Temperature/humidity sensor

84 1553-5/CXP9040776 Uen E1 | 2019-11-25

Example Scenarios

Figure 6 Buzzer and Sensor

12.6.2 Getting Started with Raspberry Pi

This section describes how to get started with Raspberry Pi.

85 1553-5/CXP9040776 Uen E1 | 2019-11-25

Example Scenarios

Steps

1. Prepare Raspberry Pi. See Prepare Raspberry Pi.

2. Log in to Partner Portal.

In the address bar of the browser, enter https://<Partner Portal host> to access Partner Portal. Then, create an account.

3. Create a device type and a device as prompted on the RESOURCES page of Partner Portal.

Note: Create the device type first.

4. Download the certificate and record topics. See Download Certificate and Record Topics.

5. Download device client development examples as prompted on the Device Client Examples page of Partner Portal.

6. Create a project based on the downloaded examples. Refer to the development guide.

7. Compile and run the project. See Compile and Run Project for Raspberry Pi.

8. Verify the data transfer between Raspberry and back-end components. See Verify Data.

12.6.2.1 Prepare Raspberry Pi

1. Install Raspberry Pi OS, for example, NOOBS version 2.0.0, by following the

guide in Raspberry Pi official website: https://www.raspberrypi.org/ downloads/noobs.

Record the IP address of Raspberry Pi after the OS is installed.

2. Set up the network. See Set Up Network.

3. Install dependency software. See Install Dependency Software.

4. Prepare the peripheral for Raspberry Pi. See Prepare Peripheral.

12.6.2.1.1 Set up Network

After the OS is installed and the peripheral is connected, you can use any SCP tool, such as PuTTY, to communicate with Raspberry Pi. Obtain the IP address of Raspberry Pi after the OS is installed on Raspberry Pi.

Set up the Wi-Fi network for Raspberry Pi through the SCP tool, such as PuTTY, as follows:

https://www.raspberrypi.org/downloads/noobs



86 1553-5/CXP9040776 Uen E1 | 2019-11-25

Example Scenarios

Steps

1. In Raspberry bash, open the wpa_supplicant.conf file:

# sudo vi /etc/wpa_supplicant/wpa_supplicant.conf

2. Add the following context to the file:

3. Edit ssid and psk as required.

4. Restart Raspberry Pi.

sudo reboot

12.6.2.1.2 Install Dependency Software

Perform the following steps to install dependency software:

Steps

1. Install wiringPi for C. Thus, you can control the GPIO of Raspberry Pi.

2. Install json-c for JSON parsing and generating.

sudo apt-get install libjson0 libjson0-dev

3. Install libssl-dev for OpenSSL and mbed TLS encryption.

sudo apt-get install libssl-dev

12.6.2.1.3 Prepare Peripheral

Use dht11 as a temperature and humidity sensor, and buzzer as an MQTT downlink warning.

ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev update_config=1 country=GB network={

ssid="helloworld" psk="12345678" key_mgmt=WPA-PSK

}

sudo apt-get install git git clone git://git.drogon.net/wiringPi cd wiringPi ./build

87 1553-5/CXP9040776 Uen E1 | 2019-11-25

Example Scenarios

To check the GPIO of Raspberry Pi, execute the following command with wiringPi for C as shown in Install Dependency Software:

# pi@raspberrypi:~ $ gpio readall

Figure 7 Raspberry Pi GPIO Sensor

GPIO

The GPIOs for sensor dht11 are arranged as follows:

Table 34 Sensor GPIO

Buzzer GPIO

The GPIOs for buzzer are arranged as follows:

Table 35 Buzzer GPIO

Pin GPIO

VCC 5 V

DATA GPIO. 1

GPIO. 1 0 V

Pin GPIO

VCC 5 V

DATA GPIO. 25

88 1553-5/CXP9040776 Uen E1 | 2019-11-25

Example Scenarios

Pin GPIO

GPIO. 1 0 V

12.6.2.2 Download Certificate and Record Topics

After a device is added, a certificate is generated for it. The certificate is used by the device to connect to Partner Portal.

Download the certificate and record the MQTT topics which are used to publish data from Raspberry Pi to Dispatcher and send data from Dispatcher to Raspberry Pi.

Download the certificate by performing the following steps:

Steps

1. Log in to Partner Portal and go to the device list.

2. Select Raspberry Pi.

Result: Information about Raspberry Pi is displayed on the right of the page.

3. Download the certificate and copy the MQTT topics to the local computer.

12.6.2.3 Compile and Run Project for Raspberry Pi

Compile the LinuxMQTTOpensslMakefile.mk with the following command:

# make -f ./LinuxMQTTOpensslMakefile.mk

Run demo_device_app with the following command:

# sudo ./demo_device_app

When the following output is displayed, it means that Raspberry Pi is able to publish or subscribe MQTT message.

89 1553-5/CXP9040776 Uen E1 | 2019-11-25

Example Scenarios

Figure 8 Example Output

12.6.2.4 Use Example Project for Raspberry Pi

The example project for Raspberry Pi can be downloaded on the Device Client Examples page from https://<Partner Portal host>.

The following figure shows the structure of the example project.

90 1553-5/CXP9040776 Uen E1 | 2019-11-25

Example Scenarios

Figure 9 Example Project Structure

12.6.2.5 Verify Data Transfer Between the Device and IoT Platform

If a message indicating that Raspberry Pi is able to publish or subscribe MQTT topics is displayed after running the project, continue to verify whether the data can be transferred between the device and IoT platform.

Both uplink and downlink data transfer need to be verified:

— Uplink data transfer means that southbound devices send data to the upstream IoT platform. The traffic is recorded on the Partner Portal GUI.

For details about the verification procedure, see Verify Uplink Data Transfer on Partner Portal.

— Downlink data transfer means that after northbound applications send requests to Dispatcher, Dispatcher forwards the requests to southbound devices.

For details about the verification procedure, see Verify Downlink Data Transfer with Dispatcher API.

12.6.2.5.1 Verify Uplink Data Transfer on Partner Portal

Use the Partner Portal GUI to verify whether the IoT platform can receive southbound device data. The procedure is as follows:

91 1553-5/CXP9040776 Uen E1 | 2019-11-25

Example Scenarios

Steps

1. Go to the device list.

2. Select the desired device.

Result: The device detail pane is displayed on the right of the page.

3. On the pane that is displayed, click the General tab.

Result: The Device Data item is displayed on the General tab page.

4. Click View.

Result: On the dialog box that is displayed, message records can be found, which indicates that device data can be received by Partner Portal.

12.6.2.5.2 Verify Downlink Data Transfer with Dispatcher API

Use Message Delivery REST API of Dispatcher to verify whether southbound devices can receive data from Dispatcher successfully.

The following table describes the request information to call the API:

Table 36 Request Information

For details about the API, refer to the Dispatcher API specifications.

Request Information Description

Request URL Format http://<dispatcher_node>/dispatch/mqtt/v2/message/

Example http://10.175.190.132:8088/dispatch/mqtt/v2/message/

Request Method POST

Request Header The request header is mandatory. The header name is Content-Type and its value is application/json. Example

Content-Type: application/json

Request Body The request body content is in JSON format. Example

{ "mqttInfo" : {

"ttl" : "10000", "QoS" : "AT_LEAST_ONCE"

}, "senderId" : "DOWNLINK", "receiverId" : "dg197e78cc9d8b49trwvti0x03mt", "protocolId" : "PIM", "payload" : "aSBhbSBmaW5lLCBhbmQgdGhhbmsgeW91"

}

92 1553-5/CXP9040776 Uen E1 | 2019-11-25

Example Scenarios

13 Life Cycle of Entities

This chapter summarizes the life cycle of different entities in Partner Portal.

13.1 Life Cycle of Partner

The life cycle of a Partner in Partner Portal is illustrated as follows:

Figure 10 Partner Life Cycle

Table 37 Partner Life Cycle

# Role Action Status in Developer Portal

Remarks

( a )

Partner Register as a new partner

Pending

( b )

System Admin Approve the partner registration and add SLA for this partner if needed

Activated The initial password is sent to the Partner Contact Person by email.

93 1553-5/CXP9040776 Uen E1 | 2019-11-25

Life Cycle of Entities

# Role Action Status in

Partner Portal

Remarks

( c )

System Admin Reject the partner registration

Deleted

( d )

System Admin Create a Partner with SLA

Activated The initial password is sent to the Partner Contact Person by email.

( e )

Partner Contact Person

Log in with the initial password and change the password

Activated

( f )

System Admin Deactivate the Partner Deactivate d

( g )

System Admin Activate the Partner Activated

( h )

System Admin / Partner Contact Person

Update the Partner information

Activated / Deactivate d

( i )

System Admin Delete the Partner Deleted

13.2 Life Cycle of Partner User

The life cycle of a Partner User in Partner Portal is illustrated as follows:

Figure 11 Partner User Life Cycle

94 1553-5/CXP9040776 Uen E1 | 2019-11-25


Table 38 Partner User Life Cycle

# Role Action Status in Partner Portal

Remarks

( a )

Partner Admin Create a user Activated The initial password is sent to the user by email.

( b )

User Log in with the initial password and change the password

Activated

( c )

User / Partner Admin

Update the user information

Activated

( d )

Partner Admin Deactivate the user Deactivate d

( e )

Partner Admin Activate the user Activated

( f )

Partner Admin Delete the user Deleted

13.3 Life Cycle of Device and Device Type

The life cycle of a Device entity or a Device Type entity in Partner Portal is illustrated as follows:

95 1553-5/CXP9040776 Uen E1 | 2019-11-25


Figure 12 Device and Device Type Life Cycle

Table 39 Device and Device Type Life Cycle


( a )

User On-board a device or device type On-boarding

( b )

(System) Provision the device or device type information

On-boarded / On- board Failed

( c )

User Update the device or device type information

Updating

( d )

(System) Provision the device or device type information

On-boarded / Update Failed

96 1553-5/CXP9040776 Uen E1 | 2019-11-25


# Role Action Status in Partner

Portal

( e )

User Delete the device or device type Deleted

13.4 Life Cycle of API Key

The life cycle of an API Key entity in Partner Portal is illustrated as follows:

Figure 13 API Key Life Cycle

Table 40 API Key Life Cycle


( a )

User Create an API Key with standard usage plan

Processing

( b )

User Create an API Key with customized usage plan

Processing

( c )

(System) Provision the API Key (Standard usage plan)

Active / Failed

Provision the API Key (Customized usage plan)

Inactive-Pending / Failed

97 1553-5/CXP9040776 Uen E1 | 2019-11-25


# Role Action Status in Partner Portal

( d )

System Admin Approve the pending API Key Active

( e )

System Admin Reject the pending API Key Inactive-Rejected

(f )

User Update the rejected API Key Inactive-Pending

( g )

User Block the active API Key Inactive-Blocked

( h )

System Admin Unblock the API Key Active

(i )

User Regenerate authentication token for the API Key

Active / Inactive- Pending / Inactive- Rejected / Inactive- Blocked

(j )

System Admin Delete the API Key Deleted

13.5 Life Cycle of OAuth Registration

The life cycle of OAuth Registration in Partner Portal is illustrated as follows:

98 1553-5/CXP9040776 Uen E1 | 2019-11-25


Figure 14 OAuth Registration Life Cycle

Table 41 OAuth Registration Life Cycle


( a )

User Create OAuth Registration Processing

( b )

(System) Provision the OAuth registration information

Success / Failed

( c )

User Update the OAuth registration information

Success

( d )

User Delete the OAuth registration Deleted

99 1553-5/CXP9040776 Uen E1 | 2019-11-25

Appendix - Error Code Rules

14 Appendix - Error Code Rules

When errors occur while using Partner Portal, an error code together with error message will return to assist in error debugging and handling.

An error code for Partner Portal GUI is an 8-digit number as follows:

xxxxxxxx

The former three digits are component service code, which represents the component service causing the error. The last five digits are error type code, which represents the specific error type of the component service.

Available component service codes are listed as follows:

— 100: Partner Portal

— 200: CDM

For details about the error types of CDM, refer to System Interface Description>CDM Interface Description>Error Codes.

— 210: Partner Manager

— 220: API Gateway and Management

— 230: Dispatcher

For the error code 20010005, 200 represents that it is an error caused by CDM and 10005 represents the specific CDM error type.

100 1553-5/CXP9040776 Uen E1 | 2019-11-25

Appendix - Error Code Rules

15 Appendix - Permissions of System Administrators

The permissions available for system administrators fall into the following two categories:

— Admin Permissions

— On-behalf Permissions

15.1 Admin Permissions

Admin permissions are common to a system administrator.

Table 42 Admin Permissions

15.2 On-behalf Permissions

System administrators can operate on behalf of Partner Users.

The permission scope of a system administrator can be larger than that of a Partner User. For example, a user does not have the API key permissions while

Permission Name Description Remarks

Manage Partners and Developers

This permission allows a system administrator to view, create, edit, delete, deactivate, and restore partners and developers.

Note:

— A system admin can only manage the partners assigned to him/her.

— If a partner is deactivated, the contact

person and all developers of that partner cannot log in with their accounts again until they are restored.

This permission is mandatory when a system administrator needs the on- behalf permissions.

View Devices This permission allows a system administrator to view devices of all partners.

Manage Device Types This permission allows a system administrator to view, create, edit, and delete system device types.

A system administrator cannot manage devices unless the system administrator has the on- behalf permissions to manage devices of a specific partner or developer.

Manage API Keys This permission allows a system administrator to view, reject, approve, block, and unblock API keys, as well as regenerate authentication tokens of the partners.

Manage LwM2M Servers This permission allows a system administrator to manage LwM2M Servers, update LwM2M Servers configuration and ACL on system device types, and unbootstrap LwM2M Servers on LwM2M devices.

101 1553-5/CXP9040776 Uen E1 | 2019-11-25

Appendix - Permissions of System Administrators

the system administrator has. In this case, the system administrator can operate on behalf of this user in terms of API keys, but the API key functions are still not available to the user.

15.2.1 API Key Permissions

The on-behalf API Key permissions are identical with the API Key Permissions of Partner Users. See API Key Permissions on page 103 for details.

15.2.2 Device Permissions

The on-behalf Device Permissions are identical with the Device Permissions of Partner Users. See Device Permissions on page 103 for details.

15.2.3 Device Type Permissions

The following table lists the on-behalf permissions on Device Type.

Table 43 On-behalf Device Type Permissions

15.2.4 OAuth Registration Permissions

The on-behalf OAuth Registration Permissions are identical with the OAuth Registration Permissions of Partner Users. See OAuth Registration Permissions on page 104 for details.

Permission Description Remarks

View Device Types Allows system administrator to view device types that belong to a specific Partner.

The view permission is the prerequisite of the other permissions. For example, if you want to create, update, or delete device types, you need to have the view permission first.

Create Device Types

Allows system administrator to create device types that belong to a specific Partner.

-

Delete Device Types

Allows system administrator to delete device types that belong to a specific Partner.

-

Update Device Types

Allows system administrator to update device types that belong to a specific Partner.

-

FOTA Allows system administrator to use the Firmware Over-Th- Air (FOTA) function on devices that belong to a specific Partner.

These three permissions apply to LwM2M devices only.

SOTA Allows system administrator to use the Software Over-The-Air (SOTA) function on devices that belong to a specific Partner.

Update LwM2M Server Configuration

Allows system administrator to configure LwM2M Servers and ACL on device types that belong to a specific Partner.

Note: This permission is particular to system administrator. The Device Type Permissions of Partner Users do not have such permission.

102 1553-5/CXP9040776 Uen E1 | 2019-11-25

Appendix - Permissions of System Administrators

15.2.5 User Management Permissions

The on-behalf User Management Permissions are identical with the User Management Permissions of Partner Users. See User Management Permissions on page 105 for details.

15.2.6 Data Storage Permission

The on-behalf Data Storage Permission is identical with the Data Storage Permission of Partner Users. See Data Storage Permission on page 105 for details.

103 1553-5/CXP9040776 Uen E1 | 2019-11-25

Appendix - Permissions of Partner Users

16 Appendix - Permissions of Partner Users

This appendix collects the permissions that are available for Partner Users.

16.1 API Key Permissions

The following table lists the permissions related to API keys:

Table 44 API Key Permissions

16.2 Device Permissions

The following table lists the permissions related to devices:

Table 45 Device Permissions


View API Keys Allows viewing API keys that belong to a specific Partner.

The view permission is the prerequisite of the other permissions. For example, if you want to create, update, or delete API keys, you need to have the view permission first.

Update API Keys Allows regenerating authentication tokens of API keys that belong to a specific Partner.

Create API Keys Allows creating API keys that belong to a specific Partner.

Delete API Keys Allows deleting API keys that belong to a specific Partner.


View Devices Allows viewing devices that belong to a specific Partner.

The view permission is the prerequisite of the other permissions. For example, if you want to create, update, or delete devices, you need to have the view permission first.

Update Devices Allows updating devices that belong to a specific Partner.

-

Create Devices Allows creating devices that belong to a specific Partner.

-

Delete Devices Allows deleting devices that belong to a specific Partner.

-

Export Devices Allows exporting device data of the devices that belong to a specific Partner.

Read and Observe LwM2M Data Allows reading and observing LwM2M data of devices that belong to a specific Partner.

These two permissions apply to LwM2M devices only.

Write and Execute LwM2M Data Allows writing and executing LwM2M data of the devices that belong to a specific Partner.

Read and Observe CoAP Data Allows reading and observing CoAP data of the devices that belong to a specific Partner.

This permission applies to CoAP devices only.

104 1553-5/CXP9040776 Uen E1 | 2019-11-25



Revoke and Renew Certificates Allows revoking or regenerating certificates of devices that belong to a specific Partner.

-

16.3 Device Type Permissions

The following table lists the permissions related device types:

Table 46 Device Type Permissions

16.4 OAuth Registration Permissions

The following table lists the permissions related to OAuth Registration:

Table 47 OAuth Registration Permissions


View Device Types Allows viewing device types that belong to a specific Partner.

The view permission is the prerequisite of the other permissions. For example, if you want to create, update, or delete device types, you need to have the view permission first.

Create Device Types Allows creating device types that belong to a specific Partner.

-

Delete Device Types Allows deleting device types that belong to a specific Partner.

-

Update Device Types Allows updating device types that belong to a specific Partner.

-

FOTA Allows using the Firmware Over The Air (FOTA) function on devices that belong to a specific Partner.

These two permissions apply to LwM2M devices only.

SOTA Allows using the Software Over- The-Air (SOTA) function on devices that belong to a specific Partner.


View OAuth Registration Allows viewing OAuth Registration that belongs to a specific Partner.

The view permission is the prerequisite of the other permissions. For example, if you want to create, update, or delete OAuth Registration, you need to have the view permission first.

Update OAuth Registration Allows regenerating client secrets of OAuth Registration that belongs to a specific Partner.

-

Create OAuth Registration Allows creating OAuth Registrations that belong to a specific Partner.

-

Delete OAuth Registration Allows deleting OAuth Registrations that belong to a specific Partner.

-

105 1553-5/CXP9040776 Uen E1 | 2019-11-25


16.5 User Management Permissions

The following table lists the permissions related to user management:

Table 48 User Management Permissions

16.6 Data Storage Permission

The following table describes the data storage permission:

Table 49 Data Storage Permission


View Users Allows viewing users and roles that belong to a specific partner.

The view permission is the prerequisite of the other permissions. For example, if you want to create, update, or delete users, you need to have the view permission first.

Update Users Allows updating, deactivating, and restoring users, as well as editing roles that belong to a specific partner.

-

Create Users Allows creating users and roles that belong to a specific partner.

-

Delete Users Allows deleting users and roles that belong to a specific partner.

-


Data Storage Allows external data storage for devices and device types that belong to a specific Partner.

This permission is available when creating a device or device type.

Partner Portal TutorialPartner Portal is a web-based self-service portal that is integrated with...

Documents

Transcript of Partner Portal TutorialPartner Portal is a web-based self-service portal that is integrated with...