Few facts to note about the device API are:
- REST based API (running over HTTP)
- Fully distributed system where your API is completely independent of other users giving security and isolation
- Your playground should be up and running for you to use the API. If the playground is down or if the subscription has expired you will not be able to use the API.
With that in mind lets dive in!
Step 1
Login to your magicblocks.io account and go to the 'Manage Apps' page from the navigation bar.
You will see the API URL. This is the URL endpoint where your API is available. Simply this is the URL which you should call via HTTP to control your device. This URL will depend on your user account which means that each magicblocks.io account will have a unique API URL.
Step 2
To consume the API you should first create an application. To do so click on the 'New app' button and enter the details of your application.
Fill in the above details to create your applications
- Name of your application
- Short description of your application. Both of them are for informative puposes.
- API key - This is the key for consuming the API. It is important that this API key is held confidentially as this would be the authenticator for the API. You will need this in the next step
Save the changes and you are good to go!
Step 3
Now that you have created an application its time to start on the API calls. You will need to use a tool like postman which you find here. You can also find this as an add-on in the Chrome app store here. We will be using this tool in the rest of this lesson. After installing and opening postman select or fill out the following info:
- URL - this is the endpoint URL for the operation you are intending to execute. The URL will take the form of : {API URL}/{device ID}/{operation name}/{args}. eg: http://c1.magicblocks.io:30002/device/id2-1476325874361/digitalOut/13/0 where
- API URL - http://c1.magicblocks.io:30002/device
- This is displayed in your 'Manage Apps' window as seen in Step 1
- device ID - id2-1476325874361
- This is the ID of the device you want to access
- operation name - digitalOut
- This is the operation you want to execute. You can find the list of available operations and the required arguments below.
- args - 13 & 0
- These are the parameters required for the operation. These parameters depend on the operation that is called and you will find the available operations the required arguments below
- HTTP method - This is the HTTP method used to invoke the operation. This will depend on the operation you are executing. It can be one of
- GET
- POST
- DELETE
- PUT
- API Key - This is the API key of your application which you created in the previous step. Go to 'Headers' tab and you will see a table with columns named 'key', 'value' & description. Enter 'api_key' under the 'key' column and the API Key in the 'value' column as shown below.
- Body - You might need to send information in the body of the API call depending on the operation. If so click on the 'Body' tab below and enter the information according to the format defined in the list below.
After setting all the parameters click on 'Send' and you will be able to call the magicblocks.io device API.
API Operations
- List all devices - Get a list of all the devices and their details
- URL - {API URL}/list
- eg: http://c1.magicblocks.io:30002/device/list
- HTTP method - GET
- Request body - blank
- Response - JSON formatted string containing a list of all available devices in the format {"Device ID":{"name":"Device name","status":"device status"}}
- eg: {"1461552825753":{"name":"ATMega1","status":"Active"},"1461552825754":{"name":"uSeeker","status":"Active"}}
- Get Device Status - Get the availability of a device
- URL - {API URL}/{device ID}/status
- eg: http://c1.magicblocks.io:30002/device/1461552825753/status
- HTTP method - GET
- Request body - blank
- Response - JSON formatted string with following parameters
- responseCode : possible values
- 200 - device online
- 410 - device offline
- 404 - device not found. check if device ID in valid.
- response
- deviceId: your device ID
- status : possible values
- online
- offline
- Get Device Class - Get the device class of a given device. This query will enable your application to query the type of the device and assume its capabilities.
- URL - {API URL}/{device ID}/class
- eg: http://c1.magicblocks.io:30002/device/1461552825753/class
- HTTP method - GET
- Request body - blank
- Response- JSON formatted string with following parameters
- responseCode: possible values
- 200 - device query successful
- 410 - device offline
- 404 - device not found. check if device ID is valid
- response: if the device is online it will give a JSON formatted string with the device capabilities with following main parameters
- mainClass - product or development board
- DEV - development board
- PROD - Deployment ready product
- subClass - type of device
- eg: MGW for magic WiFi
- version - firmware version
- description - description of the device
- operations -supported operations, the HTTP methods used to access the operations and the pins they are available on. This will differ from device to device.
- eg: status, class, digitalOut, analogOut
- Digital Out - Write to a digital I/O pin as high or low
- URL - {API URL}/{device ID}/digitalOut/{pin number}/{value}
- pin number - the pin you want to write to
- value -
- 0 - LOW
- 1 - HIGH
- HTTP method : POST
- Request body - blank
- Response body -
- responseCode
- 200 - success
- Analog Out - Write to a analog PIN as PWM
- URL - {API URL}/{device ID}/analogOut/{pin number}/{value}
- pin number - the pin you want to write to
- value -the PWM % you want to set. Should be a value between 0 and 100
- HTTP method : POST
- Request body - blank
- Response body -
- responseCode
- 200 - success
- Digital In - Read from a digital I/O pin
- URL - {API URL}/{device ID}/digitalIn/{pin number}
- pin number - the pin you want to read from
- HTTP method : GET
- Request body - blank
- Response body -
- responseCode
- 200 - success
- response
- device ID
- pin
- value
- 0 - LOW
- 1 - HIGH
- Analog In - Read from a analog pin using the ADC
- URL - {API URL}/{device ID}/analogIn/{pin number}
- pin number - the pin you want to read from
- HTTP method : GET
- Request body - blank
- Response body -
- responseCode
- 200 - success
- response
- device ID
- pin
- value - a value between 0 and 1023
- Serial Out - Write a data payload to the Serial port of the device
- URL - {API URL}/{device ID}/serialOut
- HTTP method : POST
- Request body - JSON formatted string with the following parameters
- payload - This is the data that you want to write to the serial port. This data should be base64 encoded. You can send any ASCII or binary sequence
- eg: {"payload":"dGVzdA=="}
- Response body -
- responseCode
- 200 - success
- Serial In - Read from the Serial port of the device. This is an asynchronous method where you register a callback URL and you can receive data on your callback URL. You only need to call this once in your application. However this is an idempotent operation which means multiple invokations will not have any difference
- URL - {API URL}/{device ID}/serialIn
- HTTP method : POST
- Request body - JSON formatted string with the following parameters
- callback - this is the URL in your application that you want to be called when data is received on the Serial Port. The callback URL call will be as follows:
- HTTP method: POST
- Request body:
- body:
- responseCode
- 200
- device ID
- payload - Base64 encoded data received on Serial port
- Response body -
- responseCode
- 200 - success
