How To Create a IoT Device and Push Data via REST with SAP Cloud Platform Internet of Things and SAP IoT Application Enablement

Summary

1. Introduction
2. Prerequisites
3. Create a Device and required configurations in IoT Service CF via API or Cockpit
4. Using the IoT Application Enablement – Thing Modeler
   1. Create a “Thing” in IoT AE API + device bind with IoT Service CF
   2. Create a “Thing” in IoT AE Cockpit + device bind with IoT Service CF
5. Conclusions
6. Resources

Step by Step How-To Guide

 

Introduction

At the time of publishing the latest IoT Application Enablement documentation version is 1.38

This guide is a step by step use case of SAP Cloud Platform Internet of Things and SAP IoT Application Enablement.

The examples uses example requests for Weather Station Device that measures temperature and humidity. For internal access full project docs and sources can be seen here.

Prerequisites

• IoT Application Enablement tenant configured (abbreviated next as IoT AE)
• SAP Cloud Platform Internet of Things (connected to IoT AE)
• Postman or other tool to generate requests with HTTPS on the APIs

To be able to test hands-on the folowing guide you will need a working tenant with IoT Application Enablement connected to SAP Cloud Platform Internet of Things (IoT Service CF version)

You will receive the following informations :

Topic/Variable	Example Values and/or URLs
TENANT_NAME	beta03
IoT AE Cockpit	https://iotae-<TENANT_NAME>.iot-sap.cfapps.eu10.hana.ondemand.com/launchpage/
IoT AE APIs URLs	more info about API and the app router can be found in this topic    SAP IoT Application Enablement 1.38 docs
IoT Service CF API	https://iotae-<TENANT_NAME>.eu10.cp.iot.sap/iot/core/apihub/
IoT Service CF Cockpit	https://iotae-<TENANT_NAME>.eu10.cp.iot.sap/iot/cockpit/
IoT Service CF Auth User	root (for root access)
IoT Service CF Auth Secret Password	<some_random_password>
GatewayId	3 (or 2 for MQTT)

 

Create a Device and required configurations in IoT Service CF via API

 

Create Capabilities (sensor values posible)

Save the response because you will need Capabilities Id for requests !

Example POST to http://<IoT Service CF API URL>/iot/core/api/v1/capabilities

Request Headers : 

Content-Type : application/json
Authorization : Basic <basic_auth_token_using_user_and_password>

Request Body :

{
	"name" : "weather_property_set",
	"properties" : [
		{
			"name" : "temperature",
			"dataType" : "float",
			"unitOfMeasure" : "°C"
		},
		{
			"name" : "humidity",
			"dataType" : "float",
			"unitOfMeasure" : "%"
		}
	]
}

 

Create Sensor Type(s) (capabilities are binded to one or more sensor type)

Save the response because you will need sensorTypeId for requests !

Example POST to http://<IoT Service CF API URL>/iot/core/api/v1/sensorTypes

Request Headers : 

Content-Type : application/json
Authorization : Basic <basic_auth_token_using_user_and_password>

Request Body :

{
	"name" : "weather_sensor_type",
	"capabilities" : [
		{
			"id" : "510"
		}
	]
}

 

Create a new device in the IoT Service CF.

Save the response because you will need deviceId, name and physical address for requests !

Example POST to http://<IoT Service CF API URL>/iot/core/api/v1/devices

Request Headers : 

Content-Type : application/json
Authorization : Basic <basic_auth_token_using_user_and_password>

Request Body :

{ 
   "gatewayId" : "{{gatewayId}}", 
   "name": "weather_station_device"
}

 

Create a new sensor with the correct sensor type and attach it to the created device.

Save the response because you will need sensorId, name and physical address for requests !

Example POST to http://<IoT Service CF API URL>/iot/core/api/v1/sensors

Request Headers : 

Content-Type : application/json
Authorization : Basic <basic_auth_token_using_user_and_password>

Request Body :

{
	"deviceId" : "5",
	"sensorTypeId" : "4",
	"name": "fictive_weather_company_station_1"
}

 

Test Sensor Push Data via REST network

You will need to download from IoT Service CF Cockpit the Sensor Certificates.

Be careful : each time you download the certificates the old ones will become obsolete !

The certificates must be converted to Curl format or to be added in Postman Configuration for your endpoint Url

Example POST to http://<IoT Service CF API URL>/iot/gateway/rest/measures/<DevicePhysicalAddress>

Request Headers : 

Content-Type : application/json
Authorization : Basic <basic_auth_token_using_user_and_password>

Request Body :

{
    "measureIds":["510"],
    "values":["21","80"],
    "logNodeAddr":"<SensorPhysicalAddress>"
}

 

Create a Device and required configurations in IoT Service CF Cockpit

At this moment you can’t create Capabilities and Sensor Types from the Cockpit.

You can’t create device and sensor from the cockpit.

Use the API for creating needed configuration and use the Cockpit only to view the created data

 

Using the IoT Application Enablement – Thing Modeller

IoT AE names as “Things” the devices that are connected and modelled in the system.

Each device may have multiple property sets that have “measured values” (sensor reads on a range or scale of values) and “status values” (sensor reads of boolean type).

Property set types may be of “basic data”, “measured values” or “calculates values”.

“Thing Type” is a group of from multiple property sets.

All the entities like “Property Set”, “Thing Type” and “Thing” are enclosed in a particular “Package” which is a logical group for modelling. Packages may be private or public.

More info about SAP IoT Application Enablement : here

Internal Wiki page : here

 

Create a “Thing” in IoT AE API + device bind with IoT Service CF

Create a new “Package” and “Property Set”

For package there are 2 services, one REST and one OData both of them dealing with Configuration

• Create package with REST service
• Create package with OData service

 

Create a “Thing Type” via API

• Create a Thing Type documentation

 

Create a “Thing” via API

• Things Service documentation about create

 

Create data for a “Thing”

• Create data documentation

 

Create a “Thing” in IoT AE Cockpit + device bind with IoT Service CF

 

Create a new package

• Go to IoT AE launch page (main page)
• Go to group named “IoT Thing Modeler” and click on the “Package Manager” tile.
• On top right of the packages list click on the + (plus) icon button to create a new package

Create a new “Property Set”

• Go to IoT AE launch page (main page)
• Go to group named “IoT Thing Modeler” and click on the “Thing Properties Catalog” tile.
• If you need to select your package, you can find the “Change package button” under the list
• If you have rights on the package the + (plus) icon button is enabled (under the list on the left side of the screen)
• Enter the property set name, description and select the type

Create a new “Thing Type”

• Go to IoT AE launch page (main page)
• Go to group named “IoT Thing Modeler” and click on the “Thing Modeler” tile.
• If you need to select your package, you can find the “Change Package Button” under the list
• Enter Thing Type name which is mandatory and description to have more info about it

Create a new “Thing”

• Go to IoT AE launch page (main page)
• Go to group named “IoT Thing Modeler” and click on the “Thing Modeler” tile.
• Click on the list header to change it to “Things” mode (under the search field)
• If you need to select your package, you can find the “Change package Button” under the list
• Enter Thing name and all other requested infos. For Provider binding select IoT Services 4.0

Downside in the beta version : You can’t create or bind a “Thing Location” to the “Thing” using the cockpit. You have to use the “Thing Location” Api for that

Conclusions

For IoT Service CF (SAP Cloud Platform Internet of Things) the APIs are the best way to get arround anything. The cockpit is not that friendly and if you know your way with Postman or Curl you can do more operations at the same pace with better control using the APIs.

For IoT Application Enablement is better to use the Cockpit when defining your model if you don’t need to bind it to a geographic location. If you need that you’ll have to use the APIs

 

Resources, References and Examples

 

Public videos on Youtube

 

Internal access only :

Enroll device – Weather project as example

IoT Dev Getting Started

 

General availability docs :

SAP Cloud Platform Internet of Things documentation (IoT Service CF)

IoT Service CF – Device Model

IoT Service CF – Create Device

IoT Service CF home page

IoT AE – Onboarding Things

IoT AE – Onboarding a computer a a Thing example

IoT AE API details on SAP API Business Hub

IoT AE documentation version 1.38

IoT AE home page