Helium
An mbed wrapper around the helium-client to communicate with the Helium Atom
Helium for ARM mbed
This code repository exposes an mbed library for the Helium Atom module. The Helium Atom makes it easy to securely connect IoT devices and applications to back-end IoT services.
Getting Started
See a getting started guide on the Helium site.
Supported Boards
The Helium mbed client should work with any mbed board with an available serial port.
Example Setup
Example applications can be found in the mbed Helium team.
Getting Help
If you have any questions or ideas about how to use this code - or any part of Helium - head over to the Helium Community Slack. We're standing by to help.
Contributing
Want to contribute to helium-mbed? That's awesome!
Please see CONTRIBUTING.md in this repository for details.
src/Helium.h@12:07a4782fe9f2, 2017-07-05 (annotated)
- Committer:
- Marc Nijdam
- Date:
- Wed Jul 05 12:44:35 2017 -0700
- Revision:
- 12:07a4782fe9f2
- Parent:
- 3:475fae677f2d
- Child:
- 14:af7682f4e610
native spelling of license
Who changed what in which revision?
| User | Revision | Line number | New contents of line |
|---|---|---|---|
| Marc Nijdam |
3:475fae677f2d | 1 | /* |
| Marc Nijdam |
3:475fae677f2d | 2 | * Copyright 2017, Helium Systems, Inc. |
| Marc Nijdam |
12:07a4782fe9f2 | 3 | * All Rights Reserved. See LICENSE.txt for license information |
| Marc Nijdam |
3:475fae677f2d | 4 | */ |
| Marc Nijdam |
3:475fae677f2d | 5 | |
| Marc Nijdam |
3:475fae677f2d | 6 | #ifndef HELIUM_H |
| Marc Nijdam |
3:475fae677f2d | 7 | #define HELIUM_H |
| Marc Nijdam |
3:475fae677f2d | 8 | |
| Marc Nijdam |
3:475fae677f2d | 9 | #include "mbed.h" |
| Marc Nijdam |
3:475fae677f2d | 10 | #include "helium-client/helium-client.h" |
| Marc Nijdam |
3:475fae677f2d | 11 | |
| Marc Nijdam |
3:475fae677f2d | 12 | /** |
| Marc Nijdam |
3:475fae677f2d | 13 | * \class Helium |
| Marc Nijdam |
3:475fae677f2d | 14 | * |
| Marc Nijdam |
3:475fae677f2d | 15 | * \brief Enables communication with the Helium Atom |
| Marc Nijdam |
3:475fae677f2d | 16 | * |
| Marc Nijdam |
3:475fae677f2d | 17 | * This class offers the basic ability to communicate with the Helium |
| Marc Nijdam |
3:475fae677f2d | 18 | * Atom module. |
| Marc Nijdam |
3:475fae677f2d | 19 | * |
| Marc Nijdam |
3:475fae677f2d | 20 | * See the @ref Basic.ino sketch for an example on how to create a |
| Marc Nijdam |
3:475fae677f2d | 21 | * channel and send to it. |
| Marc Nijdam |
3:475fae677f2d | 22 | * |
| Marc Nijdam |
3:475fae677f2d | 23 | */ |
| Marc Nijdam |
3:475fae677f2d | 24 | class Helium |
| Marc Nijdam |
3:475fae677f2d | 25 | { |
| Marc Nijdam |
3:475fae677f2d | 26 | public: |
| Marc Nijdam |
3:475fae677f2d | 27 | /** Create a Helium instance on a hardware serial port. |
| Marc Nijdam |
3:475fae677f2d | 28 | * |
| Marc Nijdam |
3:475fae677f2d | 29 | * @param serial The hardware serial port to use |
| Marc Nijdam |
3:475fae677f2d | 30 | */ |
| Marc Nijdam |
3:475fae677f2d | 31 | Helium(PinName tx, PinName rx); |
| Marc Nijdam |
3:475fae677f2d | 32 | |
| Marc Nijdam |
3:475fae677f2d | 33 | /** Set communication speed with the Helium Atom. |
| Marc Nijdam |
3:475fae677f2d | 34 | * |
| Marc Nijdam |
3:475fae677f2d | 35 | * This sets communication speed with the Helium Atom to the given |
| Marc Nijdam |
3:475fae677f2d | 36 | * value. |
| Marc Nijdam |
3:475fae677f2d | 37 | * |
| Marc Nijdam |
3:475fae677f2d | 38 | * @param baud The baud rate to use. |
| Marc Nijdam |
3:475fae677f2d | 39 | */ |
| Marc Nijdam |
3:475fae677f2d | 40 | int baud(enum helium_baud baud); |
| Marc Nijdam |
3:475fae677f2d | 41 | |
| Marc Nijdam |
3:475fae677f2d | 42 | /** Get information on the Helium atom |
| Marc Nijdam |
3:475fae677f2d | 43 | * |
| Marc Nijdam |
3:475fae677f2d | 44 | * Gets basic information about the Helium Atom such as it's MAC |
| Marc Nijdam |
3:475fae677f2d | 45 | * address and the current network time, if connected. |
| Marc Nijdam |
3:475fae677f2d | 46 | * |
| Marc Nijdam |
3:475fae677f2d | 47 | * @param info The information structure to fill out |
| Marc Nijdam |
3:475fae677f2d | 48 | */ |
| Marc Nijdam |
3:475fae677f2d | 49 | int info(struct helium_info * info); |
| Marc Nijdam |
3:475fae677f2d | 50 | |
| Marc Nijdam |
3:475fae677f2d | 51 | /** Connect the Helium Atom to the network. |
| Marc Nijdam |
3:475fae677f2d | 52 | * |
| Marc Nijdam |
3:475fae677f2d | 53 | * This tries to connect the Helium Atom to a nearby Element and |
| Marc Nijdam |
3:475fae677f2d | 54 | * the Helium Network. Connections can be quick or slow. A quick |
| Marc Nijdam |
3:475fae677f2d | 55 | * connection attempt to re-connect to the network using revious |
| Marc Nijdam |
3:475fae677f2d | 56 | * _connection_ state which was retrieved using %sleep. If the |
| Marc Nijdam |
3:475fae677f2d | 57 | * quick connect was not requested or if it fails a normal, slower |
| Marc Nijdam |
3:475fae677f2d | 58 | * connection attempt is made. |
| Marc Nijdam |
3:475fae677f2d | 59 | * |
| Marc Nijdam |
3:475fae677f2d | 60 | * Connect is an asynchronous operation. The given are a |
| Marc Nijdam |
3:475fae677f2d | 61 | * convenience to attempt a number of retries before returning the |
| Marc Nijdam |
3:475fae677f2d | 62 | * current connection state. |
| Marc Nijdam |
3:475fae677f2d | 63 | * |
| Marc Nijdam |
3:475fae677f2d | 64 | * @param connection A previously retrieved connection structure |
| Marc Nijdam |
3:475fae677f2d | 65 | * that reflects sleep state. |
| Marc Nijdam |
3:475fae677f2d | 66 | * |
| Marc Nijdam |
3:475fae677f2d | 67 | * @param retries The number of retries to attempt to connect. |
| Marc Nijdam |
3:475fae677f2d | 68 | * |
| Marc Nijdam |
3:475fae677f2d | 69 | * @return helium_connect_status |
| Marc Nijdam |
3:475fae677f2d | 70 | * |
| Marc Nijdam |
3:475fae677f2d | 71 | * @see Helium#connect() |
| Marc Nijdam |
3:475fae677f2d | 72 | */ |
| Marc Nijdam |
3:475fae677f2d | 73 | int connect(struct connection * connection, uint32_t retries); |
| Marc Nijdam |
3:475fae677f2d | 74 | |
| Marc Nijdam |
3:475fae677f2d | 75 | /** Short form connect to the Helium Network. |
| Marc Nijdam |
3:475fae677f2d | 76 | * |
| Marc Nijdam |
3:475fae677f2d | 77 | * This is the recommended connect call. It assumes no connection |
| Marc Nijdam |
3:475fae677f2d | 78 | * state and tries to connect for up to a 5 seconds. |
| Marc Nijdam |
3:475fae677f2d | 79 | * |
| Marc Nijdam |
3:475fae677f2d | 80 | */ |
| Marc Nijdam |
3:475fae677f2d | 81 | int connect() |
| Marc Nijdam |
3:475fae677f2d | 82 | { |
| Marc Nijdam |
3:475fae677f2d | 83 | return connect(NULL, HELIUM_POLL_RETRIES_5S); |
| Marc Nijdam |
3:475fae677f2d | 84 | } |
| Marc Nijdam |
3:475fae677f2d | 85 | |
| Marc Nijdam |
3:475fae677f2d | 86 | /** Check if the Atom is connected to the network |
| Marc Nijdam |
3:475fae677f2d | 87 | * |
| Marc Nijdam |
3:475fae677f2d | 88 | * Checks whether the Atom is connected to the network. |
| Marc Nijdam |
3:475fae677f2d | 89 | * |
| Marc Nijdam |
3:475fae677f2d | 90 | * @returns true if connected, false if not connected |
| Marc Nijdam |
3:475fae677f2d | 91 | */ |
| Marc Nijdam |
3:475fae677f2d | 92 | bool connected(); |
| Marc Nijdam |
3:475fae677f2d | 93 | |
| Marc Nijdam |
3:475fae677f2d | 94 | /** Disconnects the Atom from the network and puts it in sleep mode. |
| Marc Nijdam |
3:475fae677f2d | 95 | * |
| Marc Nijdam |
3:475fae677f2d | 96 | * This disconnects the Helium Atom from the network and puts it |
| Marc Nijdam |
3:475fae677f2d | 97 | * in sleep mode. If a connection structure is given, it is filled |
| Marc Nijdam |
3:475fae677f2d | 98 | * with sleep state which can be used in a sub-sequent connect |
| Marc Nijdam |
3:475fae677f2d | 99 | * call to quick connect to the network. |
| Marc Nijdam |
3:475fae677f2d | 100 | * |
| Marc Nijdam |
3:475fae677f2d | 101 | * @param connection Sleep connection buffer to fill in. |
| Marc Nijdam |
3:475fae677f2d | 102 | * |
| Marc Nijdam |
3:475fae677f2d | 103 | * @see Helium::sleep() for the easy version. |
| Marc Nijdam |
3:475fae677f2d | 104 | */ |
| Marc Nijdam |
3:475fae677f2d | 105 | int sleep(struct connection * connection); |
| Marc Nijdam |
3:475fae677f2d | 106 | |
| Marc Nijdam |
3:475fae677f2d | 107 | /** Disconnect the Atom and put it to sleep. |
| Marc Nijdam |
3:475fae677f2d | 108 | * |
| Marc Nijdam |
3:475fae677f2d | 109 | * This is the convenience version of sleep. A subsequent connect |
| Marc Nijdam |
3:475fae677f2d | 110 | * call will go through a normal connect cycle. |
| Marc Nijdam |
3:475fae677f2d | 111 | * |
| Marc Nijdam |
3:475fae677f2d | 112 | */ |
| Marc Nijdam |
3:475fae677f2d | 113 | int sleep() |
| Marc Nijdam |
3:475fae677f2d | 114 | { |
| Marc Nijdam |
3:475fae677f2d | 115 | return sleep(NULL); |
| Marc Nijdam |
3:475fae677f2d | 116 | } |
| Marc Nijdam |
3:475fae677f2d | 117 | |
| Marc Nijdam |
3:475fae677f2d | 118 | private: |
| Marc Nijdam |
3:475fae677f2d | 119 | Serial serial; |
| Marc Nijdam |
3:475fae677f2d | 120 | struct helium_ctx _ctx; |
| Marc Nijdam |
3:475fae677f2d | 121 | |
| Marc Nijdam |
3:475fae677f2d | 122 | friend class Channel; |
| Marc Nijdam |
3:475fae677f2d | 123 | }; |
| Marc Nijdam |
3:475fae677f2d | 124 | |
| Marc Nijdam |
3:475fae677f2d | 125 | /** |
| Marc Nijdam |
3:475fae677f2d | 126 | * \class Channel |
| Marc Nijdam |
3:475fae677f2d | 127 | * |
| Marc Nijdam |
3:475fae677f2d | 128 | * \brief A Channel to an IoT platform. |
| Marc Nijdam |
3:475fae677f2d | 129 | * |
| Marc Nijdam |
3:475fae677f2d | 130 | * Channels represent a delivery mechanism from the device to a number |
| Marc Nijdam |
3:475fae677f2d | 131 | * of supported back-end IoT platforms. |
| Marc Nijdam |
3:475fae677f2d | 132 | * |
| Marc Nijdam |
3:475fae677f2d | 133 | * To use a channel, make sure you have it set up in your Helium |
| Marc Nijdam |
3:475fae677f2d | 134 | * Dashboard and then call Channel#begin with the channel name as you |
| Marc Nijdam |
3:475fae677f2d | 135 | * configured it on the Helium Dashboard. This will automatically |
| Marc Nijdam |
3:475fae677f2d | 136 | * ensure that the device is securely authenticated and registered |
| Marc Nijdam |
3:475fae677f2d | 137 | * with the channel. |
| Marc Nijdam |
3:475fae677f2d | 138 | * |
| Marc Nijdam |
3:475fae677f2d | 139 | */ |
| Marc Nijdam |
3:475fae677f2d | 140 | class Channel |
| Marc Nijdam |
3:475fae677f2d | 141 | { |
| Marc Nijdam |
3:475fae677f2d | 142 | public: |
| Marc Nijdam |
3:475fae677f2d | 143 | /** Construct a channel. |
| Marc Nijdam |
3:475fae677f2d | 144 | * |
| Marc Nijdam |
3:475fae677f2d | 145 | * @param helium The Helium Atom to communicate with |
| Marc Nijdam |
3:475fae677f2d | 146 | */ |
| Marc Nijdam |
3:475fae677f2d | 147 | Channel(Helium * helium); |
| Marc Nijdam |
3:475fae677f2d | 148 | |
| Marc Nijdam |
3:475fae677f2d | 149 | /** Begin communicating over a channel |
| Marc Nijdam |
3:475fae677f2d | 150 | * |
| Marc Nijdam |
3:475fae677f2d | 151 | * Always call this method before calling Channel#send. Beginning |
| Marc Nijdam |
3:475fae677f2d | 152 | * communication will ensure that the device is authenticated and |
| Marc Nijdam |
3:475fae677f2d | 153 | * registered with the channel with the given name as configured |
| Marc Nijdam |
3:475fae677f2d | 154 | * in the Helium Dashboard. |
| Marc Nijdam |
3:475fae677f2d | 155 | * |
| Marc Nijdam |
3:475fae677f2d | 156 | * The `result` value will be 0 if the channel was created |
| Marc Nijdam |
3:475fae677f2d | 157 | * successfully and non-`0` otherwise. |
| Marc Nijdam |
3:475fae677f2d | 158 | * |
| Marc Nijdam |
3:475fae677f2d | 159 | * @param name The name of the channel to authenticate with. |
| Marc Nijdam |
3:475fae677f2d | 160 | * @param result An out parameter for the result of the request. |
| Marc Nijdam |
3:475fae677f2d | 161 | */ |
| Marc Nijdam |
3:475fae677f2d | 162 | int begin(const char * name, int8_t * result); |
| Marc Nijdam |
3:475fae677f2d | 163 | |
| Marc Nijdam |
3:475fae677f2d | 164 | /** Send data to this channel. |
| Marc Nijdam |
3:475fae677f2d | 165 | * |
| Marc Nijdam |
3:475fae677f2d | 166 | * Send data to a given channel. The given data is sent to the |
| Marc Nijdam |
3:475fae677f2d | 167 | * configured channel and the result as returned by the channel is |
| Marc Nijdam |
3:475fae677f2d | 168 | * put in the `result` output variable. The result value is `0` |
| Marc Nijdam |
3:475fae677f2d | 169 | * for success and non-`0` if an error occurred. |
| Marc Nijdam |
3:475fae677f2d | 170 | * |
| Marc Nijdam |
3:475fae677f2d | 171 | * @note The maximum number of bytes that can be transmitted is |
| Marc Nijdam |
3:475fae677f2d | 172 | * limited to HELIUM_MAX_DATA_SIZE (about 100 bytes). |
| Marc Nijdam |
3:475fae677f2d | 173 | * |
| Marc Nijdam |
3:475fae677f2d | 174 | * @param data The data bytes to send |
| Marc Nijdam |
3:475fae677f2d | 175 | * @param len The number of bytes in data to send |
| Marc Nijdam |
3:475fae677f2d | 176 | * @param result An out parameter for the result returned by the channel |
| Marc Nijdam |
3:475fae677f2d | 177 | */ |
| Marc Nijdam |
3:475fae677f2d | 178 | int send(void const * data, size_t len, int8_t * result); |
| Marc Nijdam |
3:475fae677f2d | 179 | |
| Marc Nijdam |
3:475fae677f2d | 180 | /** Asynchronous begin method. |
| Marc Nijdam |
3:475fae677f2d | 181 | * |
| Marc Nijdam |
3:475fae677f2d | 182 | * The Channel#begin(const char *) method is a synchronous version |
| Marc Nijdam |
3:475fae677f2d | 183 | * of this method. Sending a request to a channel returns a |
| Marc Nijdam |
3:475fae677f2d | 184 | * `token` which can be used in a subsequent call to #poll() to |
| Marc Nijdam |
3:475fae677f2d | 185 | * check for results from the remote channel. |
| Marc Nijdam |
3:475fae677f2d | 186 | * |
| Marc Nijdam |
3:475fae677f2d | 187 | * @param name The name of the channel to authenticate with. |
| Marc Nijdam |
3:475fae677f2d | 188 | * @param token The output parameter for the pending result token. |
| Marc Nijdam |
3:475fae677f2d | 189 | */ |
| Marc Nijdam |
3:475fae677f2d | 190 | int begin(const char * name, uint16_t * token); |
| Marc Nijdam |
3:475fae677f2d | 191 | |
| Marc Nijdam |
3:475fae677f2d | 192 | /** Asynchornous send method. |
| Marc Nijdam |
3:475fae677f2d | 193 | * |
| Marc Nijdam |
3:475fae677f2d | 194 | * This is the asynchronous version of the #send(void const *data, |
| Marc Nijdam |
3:475fae677f2d | 195 | * size_t int8_t *) method. |
| Marc Nijdam |
3:475fae677f2d | 196 | * |
| Marc Nijdam |
3:475fae677f2d | 197 | * @param data The data bytes to send |
| Marc Nijdam |
3:475fae677f2d | 198 | * @param len The number of bytes in data to send |
| Marc Nijdam |
3:475fae677f2d | 199 | * @param token The output parameter for the pending result token |
| Marc Nijdam |
3:475fae677f2d | 200 | */ |
| Marc Nijdam |
3:475fae677f2d | 201 | int send(void const * data, size_t len, uint16_t * token); |
| Marc Nijdam |
3:475fae677f2d | 202 | |
| Marc Nijdam |
3:475fae677f2d | 203 | /** Poll for a result token. |
| Marc Nijdam |
3:475fae677f2d | 204 | * |
| Marc Nijdam |
3:475fae677f2d | 205 | * This polls the Helium Atom for the given number of retries for |
| Marc Nijdam |
3:475fae677f2d | 206 | * the result of a given `token`. Use HELIUM_POLL_RETRIES_5S for |
| Marc Nijdam |
3:475fae677f2d | 207 | * the recommended number of retries. |
| Marc Nijdam |
3:475fae677f2d | 208 | * |
| Marc Nijdam |
3:475fae677f2d | 209 | * If succcessful the result will be helium_status_OK and the |
| Marc Nijdam |
3:475fae677f2d | 210 | * result value will be set to the result of the original request |
| Marc Nijdam |
3:475fae677f2d | 211 | * that the token represents. |
| Marc Nijdam |
3:475fae677f2d | 212 | * |
| Marc Nijdam |
3:475fae677f2d | 213 | * @param token The token to check for |
| Marc Nijdam |
3:475fae677f2d | 214 | * @param result The out parameter for the result of the given request token |
| Marc Nijdam |
3:475fae677f2d | 215 | * @param retries The number of times to retry |
| Marc Nijdam |
3:475fae677f2d | 216 | */ |
| Marc Nijdam |
3:475fae677f2d | 217 | int poll(uint16_t token, int8_t * result, uint32_t retries); |
| Marc Nijdam |
3:475fae677f2d | 218 | |
| Marc Nijdam |
3:475fae677f2d | 219 | private: |
| Marc Nijdam |
3:475fae677f2d | 220 | Helium * _helium; |
| Marc Nijdam |
3:475fae677f2d | 221 | int8_t _channel_id; |
| Marc Nijdam |
3:475fae677f2d | 222 | }; |
| Marc Nijdam |
3:475fae677f2d | 223 | |
| Marc Nijdam |
3:475fae677f2d | 224 | #endif // HELIUM_H |
| Marc Nijdam |
3:475fae677f2d | 225 | |
| Marc Nijdam |
3:475fae677f2d | 226 | /** @example Basic.cpp |
| Marc Nijdam |
3:475fae677f2d | 227 | * |
| Marc Nijdam |
3:475fae677f2d | 228 | * shows a basic example of how to construct Helium, an MQTT channel |
| Marc Nijdam |
3:475fae677f2d | 229 | * and transmitting data to that channel |
| Marc Nijdam |
3:475fae677f2d | 230 | */ |