Tools and Software
In order to use Security services suite you can leverage the following tools and speed up your development:
Postman (freeware) allows you to test the APIs to implement the services. If you do not feel comfortable with this tool, you can use an alternative solution for API testing. If you want to go ahead with Postman
Download the software from the website and install it
Download the swagger file from the REST API web page
Upload the swagger file in Postman:
click the 'Import' button near the name of your workspace and upload the swagger file.
select the 'Documentation' item from the dropdown menù 'Link this collection as'.
If you do not have yet a workspace, create a new one using the Workspace menu.
By uploading the swagger file it is automatically created a collection that contains all the Security Services REST APIs organized with the same structure of the documentation . Moreover:
the "baseUrl" that is the url of the API Interface of the u-blox Thingstream delivery platform will be automatically set to https://ssapi.services.u-blox.com/v1/
If not yet done, generate the access key and the secret from Thingstream service delivery portal, in Security Service section. Remember to download and save Access key and Secret in a secure place because the Secret is no longer accessible in the portal after the generation.
Test the connection with u-blox Thingstream server with the authentication API:
Select /authenticate API in the collection just created
configure the access Key and the Secret in the 'Body parameters' section of the API
Send the API and verify that in the 'Body' section you obtain the AuthToken and RefreshToken and that Status code is 200 (OK)
Remember that the AuthToken is valid for 1 hour. For more information, refer to the online documentation.
Using the APIs
Once the AuthToken has been generated, you can use all the other APIs. Here below an example on how to configure the parameters for /deviceprofile/get:
Create the device profile
Create a device profile in the Thingstream portal on 'Security services > Device Profile' section
As output you will have a 'Device profile name' (the one provided by you in the wizard) and a 'Device profile Uid' that is an alphanumeric string.
In Postman, select the /deviceprofile/get API.
In the 'Authorization' section, select 'Bearer Token' from the Type dropdown menu. You can also set the AuthToken for all the APIs by selecting the entire API collection 'Security Services REST API' at the root of the API list. In this case the AuthToken will used for all the APIs
Copy the 'AuthToken' without double quotes in the Token field on the right side. Be careful in pasting only the alpahnumeric string between the double quotes. Remove the double quotes and any other character like the carriage return or the new line at the end of the token (if present).
In the 'Body' section, replace the text with the one below
'TestPostman' is the Device profile name created for this example. Replace it with the name of the device profile just created. All the parameters are case sensitive. 'Page number' is a number (not a string) without double quotes and it is an optional parameter.
Send the API by clicking the blue button. Verify that the result code is 200 (OK) and check the output at the bottom of the page.
As an additional test you can:
add a tag to the device profile from the Thingstream portal accessing to the 'Device Profiles' section, then select the desired Device profile and add a tag using the proper button.
send the API specifying the tag in the body section instead of the Device profile name:
Replace 'testtag1' with the name of the tag just created by you.
Verify that the result code is 200 (OK) and check the output at the bottom of the page.
You need m-center if you want to interact directly with the module using AT command and you do not have yet available an MCU in your current setup. This is the typical scenario in which you are using an EVK.
Download the software here and install it by extracting the ZIP file in your preferred location. If you already have a previous version installed, we recommend you to install the latest version to have the entire set of AT commands pre-loaded
Connect the PC where m-center has been installed to the module and run the software
Configure the communication port using the 'Set port' button, then click 'Connect' button to establish the communication with the module
Press the 'AT Terminal' button (top right corner) to open the terminal where you can send the AT commands. On the upper right drop down menu you can select the 'Generic' item or the 'SARA-R4' or the 'SARA-R5' depending on the module you are using, to load the relevant set of commands.
Flag the 'HEX mode' checkbox on the leftside of the above menu
If you do not find the desired AT commands, you can add/edit the existing ones using the dedicated buttons
Follow the instructions in the 'Claim of Ownership' section of the Security Application note document to:
add the Device profile information to the module
check the status of the device