Creating an API Project and using the Device HTTP API to send Device Events with a Python script

This guide will demonstrate the basic use of the API Project and how one can interact with it through the Python programming langauge.

This can be utilized to integrate your own finished embedded devices into Atmosphere IoT without having to use the generated firmware from Atmosphere IoT Studio. You could also use this to create your own Edge Gateway to Atmosphere IoT solution. For example having a gateway read data from fleet of BLE devices to then register and forward data to Atmosphere IoT.

If you wish to read the entire API that is available for Atmosphere IoT look here Atmosphere IoT Platform API v2

Prerequisite: You should already have an Atmosphere account.

It's recommended to have a moderate understanding of Atmosphere IoT Studio, HTTP Protocol, and Python prior to attempting this guide. The guide doesn't detail usage of Atmosphere IoT Studio and presumes the reader understands basic concepts of IoT Studio projects.

Requirements

  • A computer with the Python programming language installed

Step 1 of 4: Create a New API Project in Atmosphere IoT Studio

The first step for this guide is to create a new Atmosphere IoT Studio project of the type API Project. This API Project will give you the ability to define the behaviour of the Application view as well as the Cloud without needing a specific embedded device to load firmware onto.

  1. Navigate to the “Projects” section of Atmosphere IoT using the right side navigation menu
  2. Click on the “New Project” icon
  3. From the “Create New Project” modal find and select the API Project type, set a name for the new project and click “Create”

You will now find your self in a new project that includes the tabs for the “Application” and the “Cloud” but does not include any embedded plane.

Step 2 of 4: Creating a Device Event and having it stored in a Cloud Storage

For this step we will begin by creating a Device Event and then storage the data that comes to the cloud as that event into a Cloud Storage. Device Events are values that are sent by a device to the cloud that can then be processed by the logic that has been defined in your Atmosphere Project.

  1. Navigate in your project to the “Cloud” tab
  2. From the “Element Toolbox” click on the “Device Event” element to add it to the designer area
  3. From the “Element Toolbox” click on the “Cloud Storage” element to add it to the designer area
  4. Drag a connector from the newly added “DeviceEvent” to the newly created “CloudStorage”
  5. Save your project by pressing the Save button in the top right

API Project Getting Started

Your project is now ready to recieve data from a Device Event and storage that data within a Cloud Storage.

Step 3 of 4: Registering a Device via the API

Now that we have create a project we will now want to register a device against the project you just created.

If you run this following script a second time it will overwrite the previous credentials that were saved on your system!

  1. While in your project you now want to click on the Info“Info” button to access the project info
  2. Copy the Project UUID and Version UUID for use in the next steps
  3. You will need to get an API token from your account’s security area. If one does not already exist you may need to generate a new token
  4. Open your favorite text editor and save the following code to a file called “register.py”
import requests
import json

response = requests.post('https://platform.atmosphereiot.com/v2/devices', 
	headers={
		"api_auth_token":"<INSERT THE API TOKEN COPIED FROM STEP 3>"
	},
	json={
		"name": "My API Device", #Name for your new device
		"projectUuid": "<INSERT THE PROJECT UUID COPIED FROM STEP 2>",
		"versionUuid": "<INSERT THE VERSION UUID COPIED FROM STEP 2>",
		"protocol":"",
		"protocols":[]
	})

# If we don't get back a 201 something went wrong, throw an error
if response.status_code != 201:
	print("An error occured while adding the new device!")

#Nothing went wrong so lets store our credentials in a file for later
else:
	print(response.json())
	credFile = open("atmo_creds.json", "w");
	credFile.write(json.dumps(response.json()));
	credFile.close();
  1. You can now run the script to register a device by running python register.py

You should now have in the same directory that you ran this script from a file called “atmo_creds.json” this file contains your device’s credentials for sending device events in the next step. You will also now see that in the “Devices” area of Atmosphere IoT a new device called “My API Device”. This is the device you just created with the above script and will begin to send data to.

Step 4 of 4: Sending a Device Event via the API

Now that we have the “atmo_creds.json” for your new device we can write another python script that will utilize those credentials to send up Device Events. We will now send a device event through the Device Event Element we created in the Cloud plane of our project called “DeviceEvent”.

If you changed the name property of the Device Event Element we added in Step 2 you will need to change "DeviceEvent" here to reflect that value

  1. In the same directory as the atmo_creds.json file create a new file called “send_data.py” with the following script
import sys
import json
import requests

if len(sys.argv) < 2:
	print('Please provide a JSON value to send')
	exit();

argData = json.loads(sys.argv[1])

credsFile = open("atmo_creds.json", "r")
credsData = json.loads(credsFile.read())

response = requests.post('https://platform.atmosphereiot.com/v2/events/device', 
	headers={
		"cloud":credsData.get("token")
	},
	params={
		"elementName":"DeviceEvent"
	},
	json=argData) 
  1. You can now send data to your Device in Atmosphere by running the following command python send_data.py 12 will send the number 12 to your cloud plane to be processed and stored into the cloud storage

With this example you can modify it or use it within your own code to send data from other sources.