# mbed-connector-api-python

**Repository Path**: mirrors_ARMmbed/mbed-connector-api-python

## Basic Information

- **Project Name**: mbed-connector-api-python
- **Description**: python library for using connector.mbed.com
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2020-08-08
- **Last Updated**: 2025-12-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

## mbed-connector-python 
A python package to use the [mbed Device Connector](https://connector.mbed.com/) REST interface to control IoT devices running [mbed Client](https://www.mbed.com/en/development/software/mbed-client/)

[![Circle CI](https://circleci.com/gh/ARMmbed/mbed-connector-api-python.svg?style=svg)](https://circleci.com/gh/ARMmbed/mbed-connector-api-python)
[![PyPI version](https://badge.fury.io/py/mbed-connector-api.svg)](https://badge.fury.io/py/mbed-connector-api)
[![ReadTheDocs version](https://readthedocs.org/projects/mbed-connector-api-python/badge/?version=latest)](http://mbed-connector-api-python.readthedocs.org/en/latest/)

### Purpose
This library is meant to be used in conjuntion with the [connector.mbed.com](https://connector.mbed.com/) service. This library uses the requests library to interface to mbed connector via HTTP REST calls. Details on the mbed connector RESTful interface can be found [here](https://docs.mbed.com/docs/mbed-device-connector-web-interfaces/en/latest/). You can use this library either as part of a webapp or locally on your computer.

### API
* [docs.mbed.com](https://docs.mbed.com/docs/mbed-connector-api-python) - Read the Docs style documentation.
* [pdf](https://docs.mbed.com/projects/mbed-connector-api-python/downloads/pdf/master/) - Autogenerated PDF of docs
* [Other Offline Formats](https://docs.mbed.com/projects/mbed-connector-api-python/downloads/) - All other build artifacts for offline viewing (Epub, HTML-zip...etc)

### Installation

#### pip
Install the mdc-api package from pip. You may need to use `sudo` on your system.
```python
pip install -U mbed-connector-api
```

#### setup.py
Clone the repository, then run the following command inside the downloaded folder. 

```python
sudo python setup.py install
```

### Examples
These examples demonstrate how to use the mbed-connector python library in two instances. The first example is a remotely hosted webapp where a public URL can be registered as a webhook callback address. Second is locally on your computer where you will use LongPolling to constantly poll the server for responses to your requests. LongPolling is necessary as machines behind firewalls cannot easily register a public url to handle callbacks / webhooks.  
There are more examples in the Docs.

Other examples can be seen here:
- [quickstart](https://github.com/armmbed/mbed-connector-api-python-quickstart)
- [github build failure alarm](https://github.com/BlackstoneEngineering/connector-example-python-github-build-failure)
- [log values to excel file](https://github.com/BlackstoneEngineering/connector-log-to-excel)

##### web app
For a web app we do not need long polling, instead we can simply register a webhook url and then handle all callbacks to that URL appropriately. This method is reccomended for releases as it is less resource intensive than constantly long polling. 
```python
import web
import mbed_connector_api
import json

# map URL to class to handle requests
urls = (
	'/', 'index',
	'/callbackURL','callbackFunction',
	'/start','start',
)

token = "CHANGEME" # Get from connector.mbed.com
connector = mbed_connector_api.connector(token)

class index:
	def GET(self):
		return "Hi there, please click 'start' to begin polling mbed Device Connector"

class callbackFunction:
	# handle asynchronous events
	def PUT(self):
		if web.data: # verify there is data to process
			print json.loads(web.data()).keys()
			connector.handler(web.data()) # hand the data to the connector handler
		return web.ok

# 'notifications' are routed here
def notificationHandler(data):
	print "\r\nNotification Data Received :\r\n %s" %data['notifications']


class start:
	def GET(self):
		e = connector.putCallback("https://python-workspace-mbedaustin.c9users.io:8080/callbackURL")
		while not e.isDone():
			None
		if e.error:
			return e.error.errType
		else:
			connector.setHandler('notifications', notificationHandler) # send 'notifications' to the notificationHandler FN
			return "Roger Dodger, started her up!"
			
if __name__ == "__main__":
	app = web.application(urls, globals())
	app.run()
	connector.debug(True) # turn on optional debugging
	e = connector.putCallback("https://python-workspace-mbedaustin.c9users.io:8080/callbackURL") # Change to match your workspace
	while not e.isDone():
		None
	if e.error:
		print "ERROR in initialization : " + e.error.errType
```
In the code above you can see the webhook URL accepts PUT requests. In the initialization of the flask webapp we register the callback to connector with `putCallback("mywebapp.com:8080/webhook)`. You will need to change `mywebapp.com` to match the public url of your web app, also change the `8080` to the port your web app is running on.


##### locally hosted
Using the library locally on your computer will require the use of LongPolling. To initialize the library you will need to import it and then instantiate an instance with the API key taken from [connector.mbed.com](https://connector.mbed.com/#accesskeys). Next you will need to `startLongPolling()` which will spin off a thread that will constantly ping the mbed connector service, when it finds updates that match requests you have made it will trigger the callback function you registered. 

```python
# Initialization
import mbed_connector_api
x = mbed_connector_api.connector("insert api key from [connector.mbed.com](https://connector.mbed.com/#accesskeys)")
x.startLongPolling()

# Use 
x.getEndpoints() # returns a  list of all endpoints on your domain
x.getResources("EndpointName") # returns all resources of an endpoint
x.putResourceValue("EndpointName","Resource","Value") # send the "Value" to the "Resource" over a PUT request
x.postResourceValue("EndpointName","Resource","Value") # send the "Value" to the "Resource" over a POST request
y = x.getResourceValue("EndpointName","Resource")  # check the y.isDone() funciton to see when the request completes, the result will then be in y.result. The Resource should be of the form "/X/Y/Z"
if y.isDone():
    if not y.error:
        print("The value of y is " +y.result)
    else:
        print("Error : %s",y.error.error)

##########

# alternatively you can call a callback fn instead
def callbackFn(dataIn, rawData):
    print "TestFN"
    print "data : " +str(dataIn)
    print "raw JSON Data : " +str(rawData)

x.getResourceValue("EndpointName","Resource",callbackFn)

##########

x.subscribeToResource("Endpoint","Resource",callbackFN) # This will call the callbackFn every time the Endpoint/Resource value changes.

```

### Extras
#### Debug
This module uses the logging module. To enable more robust debugging initialize your object instance and then use the `.debug(True)` method to enable more robust debugging of the module

### Tests
This module uses the `nose` test framework. You can install it by running `pip install nose` , then running `nosetests` in the top level directory for this project. Currently tests are desiged to test a hard coded endpoint. You will need to change the endpoint name and API Token in the test files in the `mbed_connector_api/tests` directory. 

### License
Apache 2.0