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

Summary

Introduction
Prerequisites
Create a Device and required configurations in IoT Service CF via API or Cockpit
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
Conclusions
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 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

5 Comments

You must be Logged on to comment or reply to a post.

Former Member August 30, 2017 at 4:07 am

Is there a video available for this step-by-step implementation?

like (0)
1. Radu Constantin Simen Post authorSeptember 6, 2017 at 11:28 am
  
  There are some training videos on Youtube for IoT AE recorded by Marcus Behrens :
  
  https://www.youtube.com/watch?v=vCxXiY6OL34&list=PLWV533hWWvDnP5S4PLiC1d-J7hj1sjZn6
  
  like (0)
Vaibhav Surana August 30, 2017 at 1:21 pm

Hi,

Nice guide, was able to do as you mentioned. However is there a way to create

However is there a way to create a device mqtt protocol using APIs so can send MQTT data?

Regards

Vaibhav Surana

like (1)
1. Christian Schuerings August 31, 2017 at 9:35 am
  
  Hi Vaibhav,
  
  if you want to create a device which sends data via MQTT to the MQTT Cloud Gateway, you just need to change the gatewayId within the request body in step:
  Create a new device in the IoT Services
  { “gatewayId” : “{{gatewayId}}”, “name”: “weather_station_device” }
  
  Here change the value to e.g. 2, which should be by default the MQTT Cloud Gateway.
  
  Afterwards you are able to send data for this MQTT device like this:
  https://help.sap.com/viewer/e765b2a5b99540ce84da397c20cc1993/Cloud/en-US
  
  Best Regards
  Christian
  
  like (0)
  1. Vaibhav Surana October 18, 2017 at 2:52 pm
    
    Hi Christian,
    
    Thanks a lot.
    
    This was helpful.
    
    Regards
    
    Vaibhav Surana
    
    like (1)