1. What is OpenChirp?
2. What Problem Does OpenChirp Solve?
3. How does OpenChirp Accomplish Its Goals?
4. Who does OpenChirp target and is it actually open-source?
5. Quick Links
6. OpenChirp Architecture
7. Get Started
8. Getting Help

OpenChirp is a management framework on top of LoRaWAN that provides data context, storage, visualization, and access control over the web. LoRaWAN is an emerging Low-Power Wide-Area Networking (LP-WAN) protocol designed to support battery-operated devices that want to send just a few bytes of data but over long distances. Devices typically transmit 1-2km in urban areas and up to 15km in open space. OpenChirp is currently powering a LoRaWAN Network that started at Carnegie Mellon University but has spread to the City of Pittsburgh and beyond.

OpenChirp solves a few key problems in how people use LP-WANs:

1. It provides an open and free interface to a hosted LoRaWAN server
2. It translates compressed binary byte-streams into JSON for applications
3. It provides time series storage for transducer data
4. It allows users to share data streams
5. It allows users to securely connect their own gateways to help grow the network
6. It provides a single cohesive representation for multiple field-bus and LPWAN interfaces

OpenChirp accomplishes the above goals by providing an infrastructure that sits above the LoRaWAN server with a set of APIs that allow users to register and describe LoRa gateways, devices and data flows. The system provides services that can be attached to data streams that can perform operations ranging from basic data storage to binary-to-json packing and unpack. A RESTful interface is used to configure meta-information about devices and set access control privileges that define how other users can interact with data streams. OpenChirp currently provides a simple way to link user-owned LoRa gateways into the system making it easy to create a LoRa Hotspot in your area. We are developing services that can integrate other types of field-bus devices to work under a uniform framework. To facilitate community involvement we are developing a set of online tutorials for how to create gateways and clients using commercially available devices.

OpenChirp targets University Researchers, but we hope it can be used by anyone. We host an instance of OpenChirp at openchirp.io for people that want to explore while also helping expand our network. However, the entire stack including web portal, services, back-end and client software is open-source. This means it is totally possible to run your own entirely private instance of Open-Chirp (we are still working on a docker container and documentation). We eventually want to add federation capabilities for those that want to host their own private instances and still contribute network coverage.

• REST API Documentation
• Overview Presentation
• Simple Device Tutorial
• Tutorial for adding a LoRa Device
• Tutorial for adding a LoRa Gateway to the network
• PubSub Overview
• Time Series Data

Get started by trying the Simple Device Tutorial that you can complete entirely using the web portal.

1. Setup a gateway
2. Setup a sensor

Post on our Forum: http://community.openchirp.io

The OpenChirp Architecture is split into two main components: a control plane and a data plane. The control plane is exposed through a REST interface and is used to create devices, define their properties, and to manage who or what has access to them. The data plane uses MQTT to allow access to real-time data streams using a publish subscriber model. Each device created by the control plane has a corresponding MQTT end-point. The system currently uses OAuth 2 with Google's authorization server. Access Control Lists (ACLs) are uniform across the REST and MQTT frameworks using a common database. All meta-data is stored using MongoDB and time series data is currently using InfluxDB. For LoRa support, we are leveraging the excellent Open Source LoRaServer developed by Broocar.

Devices are defined as a set of Transducers and Commands. Each devices has an MQTT end-point (openchirp/devices/UID) and a set of key / value pair properties. These properties can be used to keep track of additional information that might be used to describe a device. Transducers are used to represent each sensor or actuator associated with the device and can be found inside each device within the MQTT tree. They are have a few properties such as Name, Unit, Actuation Flag, Value and a server timestamp for when they were last updated. The Unit is a human readable tag that defines that unit for the transducer. Whenever possible, we suggest using a standard SI value. Sometimes units can be described as types like "binary" or "enumeration". The Actuation Flag describes if the transducers is a sensor or actuator, since only actuators can be connected with a Command. A Command is a simple macro used to link a common actuation value with a transducer. For example, "Light On" might be an alias for passing the value 1 to a binary light actuator. In a more complex example, "Light On" could capture an arbitrarily complex JSON message that needs to be published to a device's transducer. Commands are useful within the OpenChirp web portal for performing quick actuations and can also be represented by a public URL link to share with outside applications.

Device Templates capture the Transducers and Commands of commonly used devices. It is possible to create a template from any existing device. This device template can then be used when creating a new device to populate all of the transducers, commands and any attached services. These templates represent the golden standard of how a device should be represented which helps provide users typical unit and transducer names. Users must be in the "Developer" role to create publicly viewable templates.

Service are software components designed to run within the OpenChirp framework that can easily link to device to perform various continuous background processing. These would ideally be processing elements that should be hosted in the cloud to perform continuous stream processing on data. Some examples include: (1) a Time Series Database service that links to a device to collect and store transducer values, (2) the LoRaWAN Service that connects a device with a LoRaWAN end-point and (3) a Trigger service that links to a device and fires an event if a user-defined threshold is reached. The OpenChirp framework helps define service properties (i.e. parameters required by the service) and provides support for linking services with device and getting per-device status information from the service.

"Developer" role is required for installing new services that are publically accessible. The service also needs to be hosted in the cloud somewhere (typically on our OpenChirp server). For more information about developing services, see our Service Development Tutorial.

Authentication in OpenChirp is managed using the OAuth2 protocol which can be connected to several authentication servers. By default, we use Google for authentication for the web portal. For devices, services and user applications, the system provides a set of tokens which can be used with basic authentication, but with limited scope. This allows an easy way for both REST and MQTT connections for devices and applications without requiring full OAuth support. Note that only a hash of tokens is stored on the server, so you must regenerate tokens for a new copy which will invalidate the previous tokens.

Device Tokens are available to device owners in the web portal under the Security tab for each device. Device tokens are scoped in access (both REST and MQTT) such that they can only read and write to that specific device. In basic auth, the username is the device ID and the password is the device token.

Service Tokens are available to service creators and provide a service application with read as well as write or execute access to any linked devices. Note, currently service tokens provide full access in MQTT to all devices, but this will be restricted in a future release. REST access is limited as described above. The user name for the service token should be the same as the user that created the service.

User API Tokens can be generated in the “My Profile” tab in the upper right of the web portal. These tokens can be used with your user id (email) as the name and the token as the password for basic auth. This token provides any script or program with the same access as the user. The token can also be deleted from the user profile page.

Each Command in the system can have a Public URL Link generated by any user with execute access to the command. If POST is called on the link, the command executes. If GET is called on this link, a button is provided that when clicked launches the command. GET is wrapped in a button to avoid accidental actuation when posting or sharing the link as many programs will execute the link to generate a thumbnail etc. Public links are connected to the command and user, so if the user is removed from the execute list for the device then the link no longer works.

Access Control Lists (ACLs) can be attached to devices and are comprised of Users and Groups with Read, Write and Execute permissions. Any user can create a group and add additional users to the group. Additional users can be given write permissions to be able to manage the group itself. Read permissions allow access to transducers as well as meta information. The Execute permission allows users or groups to be able to also run commands. The Write permission allows full access to the device including being able to modify or delete all content. Permissions can be controlled using the REST interface or the web portal. All ACLs are consistent between the REST interface and MQTT (some restrictions currently apply to MQTT access control).