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@23:cc2c1d1ed159, 2017-09-05 (annotated)
- Committer:
- Marc Nijdam
- Date:
- Tue Sep 05 13:56:03 2017 -0700
- Revision:
- 23:cc2c1d1ed159
- Parent:
- 22:062758492f31
Add configuration API support
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 |
14:af7682f4e610 | 9 | #include "BufferedSerial.h" |
| Marc Nijdam |
3:475fae677f2d | 10 | #include "helium-client/helium-client.h" |
| Marc Nijdam |
17:f38730193da3 | 11 | #include "mbed.h" |
| Marc Nijdam |
3:475fae677f2d | 12 | |
| Marc Nijdam |
3:475fae677f2d | 13 | /** |
| Marc Nijdam |
3:475fae677f2d | 14 | * \class Helium |
| Marc Nijdam |
3:475fae677f2d | 15 | * |
| Marc Nijdam |
3:475fae677f2d | 16 | * \brief Enables communication with the Helium Atom |
| Marc Nijdam |
3:475fae677f2d | 17 | * |
| Marc Nijdam |
3:475fae677f2d | 18 | * This class offers the basic ability to communicate with the Helium |
| Marc Nijdam |
3:475fae677f2d | 19 | * Atom module. |
| Marc Nijdam |
3:475fae677f2d | 20 | */ |
| Marc Nijdam |
3:475fae677f2d | 21 | class Helium |
| Marc Nijdam |
3:475fae677f2d | 22 | { |
| Marc Nijdam |
3:475fae677f2d | 23 | public: |
| Marc Nijdam |
3:475fae677f2d | 24 | /** Create a Helium instance on a hardware serial port. |
| Marc Nijdam |
3:475fae677f2d | 25 | * |
| Marc Nijdam |
3:475fae677f2d | 26 | * @param serial The hardware serial port to use |
| Marc Nijdam |
3:475fae677f2d | 27 | */ |
| Marc Nijdam |
3:475fae677f2d | 28 | Helium(PinName tx, PinName rx); |
| Marc Nijdam |
3:475fae677f2d | 29 | |
| Marc Nijdam |
3:475fae677f2d | 30 | /** Set communication speed with the Helium Atom. |
| Marc Nijdam |
3:475fae677f2d | 31 | * |
| Marc Nijdam |
3:475fae677f2d | 32 | * This sets communication speed with the Helium Atom to the given |
| Marc Nijdam |
3:475fae677f2d | 33 | * value. |
| Marc Nijdam |
3:475fae677f2d | 34 | * |
| Marc Nijdam |
3:475fae677f2d | 35 | * @param baud The baud rate to use. |
| Marc Nijdam |
3:475fae677f2d | 36 | */ |
| Marc Nijdam |
3:475fae677f2d | 37 | int baud(enum helium_baud baud); |
| Marc Nijdam |
3:475fae677f2d | 38 | |
| Marc Nijdam |
3:475fae677f2d | 39 | /** Get information on the Helium atom |
| Marc Nijdam |
3:475fae677f2d | 40 | * |
| Marc Nijdam |
3:475fae677f2d | 41 | * Gets basic information about the Helium Atom such as it's MAC |
| Marc Nijdam |
3:475fae677f2d | 42 | * address and the current network time, if connected. |
| Marc Nijdam |
3:475fae677f2d | 43 | * |
| Marc Nijdam |
3:475fae677f2d | 44 | * @param info The information structure to fill out |
| Marc Nijdam |
3:475fae677f2d | 45 | */ |
| Marc Nijdam |
3:475fae677f2d | 46 | int info(struct helium_info * info); |
| Marc Nijdam |
3:475fae677f2d | 47 | |
| Marc Nijdam |
3:475fae677f2d | 48 | /** Connect the Helium Atom to the network. |
| Marc Nijdam |
3:475fae677f2d | 49 | * |
| Marc Nijdam |
3:475fae677f2d | 50 | * This tries to connect the Helium Atom to a nearby Element and |
| Marc Nijdam |
3:475fae677f2d | 51 | * the Helium Network. Connections can be quick or slow. A quick |
| Marc Nijdam |
3:475fae677f2d | 52 | * connection attempt to re-connect to the network using revious |
| Marc Nijdam |
3:475fae677f2d | 53 | * _connection_ state which was retrieved using %sleep. If the |
| Marc Nijdam |
3:475fae677f2d | 54 | * quick connect was not requested or if it fails a normal, slower |
| Marc Nijdam |
3:475fae677f2d | 55 | * connection attempt is made. |
| Marc Nijdam |
3:475fae677f2d | 56 | * |
| Marc Nijdam |
3:475fae677f2d | 57 | * Connect is an asynchronous operation. The given are a |
| Marc Nijdam |
3:475fae677f2d | 58 | * convenience to attempt a number of retries before returning the |
| Marc Nijdam |
3:475fae677f2d | 59 | * current connection state. |
| Marc Nijdam |
3:475fae677f2d | 60 | * |
| Marc Nijdam |
3:475fae677f2d | 61 | * @param connection A previously retrieved connection structure |
| Marc Nijdam |
3:475fae677f2d | 62 | * that reflects sleep state. |
| Marc Nijdam |
3:475fae677f2d | 63 | * |
| Marc Nijdam |
3:475fae677f2d | 64 | * @param retries The number of retries to attempt to connect. |
| Marc Nijdam |
3:475fae677f2d | 65 | * |
| Marc Nijdam |
3:475fae677f2d | 66 | * @return helium_connect_status |
| Marc Nijdam |
3:475fae677f2d | 67 | */ |
| Marc Nijdam |
17:f38730193da3 | 68 | int connect(struct connection * connection = NULL, |
| Marc Nijdam |
17:f38730193da3 | 69 | uint32_t retries = HELIUM_POLL_RETRIES_5S); |
| Marc Nijdam |
3:475fae677f2d | 70 | |
| Marc Nijdam |
3:475fae677f2d | 71 | /** Check if the Atom is connected to the network |
| Marc Nijdam |
3:475fae677f2d | 72 | * |
| Marc Nijdam |
3:475fae677f2d | 73 | * Checks whether the Atom is connected to the network. |
| Marc Nijdam |
3:475fae677f2d | 74 | * |
| Marc Nijdam |
3:475fae677f2d | 75 | * @returns true if connected, false if not connected |
| Marc Nijdam |
3:475fae677f2d | 76 | */ |
| Marc Nijdam |
3:475fae677f2d | 77 | bool connected(); |
| Marc Nijdam |
3:475fae677f2d | 78 | |
| Marc Nijdam |
3:475fae677f2d | 79 | /** Disconnects the Atom from the network and puts it in sleep mode. |
| Marc Nijdam |
3:475fae677f2d | 80 | * |
| Marc Nijdam |
3:475fae677f2d | 81 | * This disconnects the Helium Atom from the network and puts it |
| Marc Nijdam |
3:475fae677f2d | 82 | * in sleep mode. If a connection structure is given, it is filled |
| Marc Nijdam |
3:475fae677f2d | 83 | * with sleep state which can be used in a sub-sequent connect |
| Marc Nijdam |
3:475fae677f2d | 84 | * call to quick connect to the network. |
| Marc Nijdam |
3:475fae677f2d | 85 | * |
| Marc Nijdam |
3:475fae677f2d | 86 | * @param connection Sleep connection buffer to fill in. |
| Marc Nijdam |
3:475fae677f2d | 87 | */ |
| Marc Nijdam |
17:f38730193da3 | 88 | int sleep(struct connection * connection = NULL); |
| Marc Nijdam |
3:475fae677f2d | 89 | |
| Marc Nijdam |
19:be9553194a4e | 90 | /** Checks if the Atom needs resetting. |
| Marc Nijdam |
19:be9553194a4e | 91 | * |
| Marc Nijdam |
19:be9553194a4e | 92 | * Checks if the Atom needs a reset. This is set over the air by |
| Marc Nijdam |
19:be9553194a4e | 93 | * the Helium network when the Helium Atom has a firmware update |
| Marc Nijdam |
19:be9553194a4e | 94 | * ready to apply. |
| Marc Nijdam |
19:be9553194a4e | 95 | * |
| Marc Nijdam |
19:be9553194a4e | 96 | * @returns true if the Atom needs to be reset, false otherwise. |
| Marc Nijdam |
19:be9553194a4e | 97 | */ |
| Marc Nijdam |
19:be9553194a4e | 98 | bool needs_reset(); |
| Marc Nijdam |
19:be9553194a4e | 99 | |
| Marc Nijdam |
18:c735140666d1 | 100 | /** Resets the Atom. |
| Marc Nijdam |
18:c735140666d1 | 101 | * |
| Marc Nijdam |
18:c735140666d1 | 102 | * This resets the Atom. Use this method when `needs_reset` |
| Marc Nijdam |
18:c735140666d1 | 103 | * returns true to apply any pending firmware updates to the Atom. |
| Marc Nijdam |
18:c735140666d1 | 104 | */ |
| Marc Nijdam |
18:c735140666d1 | 105 | int reset(); |
| Marc Nijdam |
18:c735140666d1 | 106 | |
| Marc Nijdam |
3:475fae677f2d | 107 | |
| Marc Nijdam |
3:475fae677f2d | 108 | private: |
| Marc Nijdam |
3:475fae677f2d | 109 | struct helium_ctx _ctx; |
| Marc Nijdam |
17:f38730193da3 | 110 | BufferedSerial serial; |
| Marc Nijdam |
3:475fae677f2d | 111 | |
| Marc Nijdam |
3:475fae677f2d | 112 | friend class Channel; |
| Marc Nijdam |
23:cc2c1d1ed159 | 113 | friend class Config; |
| Marc Nijdam |
3:475fae677f2d | 114 | }; |
| Marc Nijdam |
3:475fae677f2d | 115 | |
| Marc Nijdam |
3:475fae677f2d | 116 | /** |
| Marc Nijdam |
3:475fae677f2d | 117 | * \class Channel |
| Marc Nijdam |
3:475fae677f2d | 118 | * |
| Marc Nijdam |
3:475fae677f2d | 119 | * \brief A Channel to an IoT platform. |
| Marc Nijdam |
3:475fae677f2d | 120 | * |
| Marc Nijdam |
3:475fae677f2d | 121 | * Channels represent a delivery mechanism from the device to a number |
| Marc Nijdam |
3:475fae677f2d | 122 | * of supported back-end IoT platforms. |
| Marc Nijdam |
3:475fae677f2d | 123 | * |
| Marc Nijdam |
3:475fae677f2d | 124 | * To use a channel, make sure you have it set up in your Helium |
| Marc Nijdam |
3:475fae677f2d | 125 | * Dashboard and then call Channel#begin with the channel name as you |
| Marc Nijdam |
3:475fae677f2d | 126 | * configured it on the Helium Dashboard. This will automatically |
| Marc Nijdam |
3:475fae677f2d | 127 | * ensure that the device is securely authenticated and registered |
| Marc Nijdam |
3:475fae677f2d | 128 | * with the channel. |
| Marc Nijdam |
3:475fae677f2d | 129 | * |
| Marc Nijdam |
3:475fae677f2d | 130 | */ |
| Marc Nijdam |
3:475fae677f2d | 131 | class Channel |
| Marc Nijdam |
3:475fae677f2d | 132 | { |
| Marc Nijdam |
3:475fae677f2d | 133 | public: |
| Marc Nijdam |
3:475fae677f2d | 134 | /** Construct a channel. |
| Marc Nijdam |
3:475fae677f2d | 135 | * |
| Marc Nijdam |
3:475fae677f2d | 136 | * @param helium The Helium Atom to communicate with |
| Marc Nijdam |
3:475fae677f2d | 137 | */ |
| Marc Nijdam |
3:475fae677f2d | 138 | Channel(Helium * helium); |
| Marc Nijdam |
3:475fae677f2d | 139 | |
| Marc Nijdam |
3:475fae677f2d | 140 | /** Begin communicating over a channel |
| Marc Nijdam |
3:475fae677f2d | 141 | * |
| Marc Nijdam |
3:475fae677f2d | 142 | * Always call this method before calling Channel#send. Beginning |
| Marc Nijdam |
3:475fae677f2d | 143 | * communication will ensure that the device is authenticated and |
| Marc Nijdam |
3:475fae677f2d | 144 | * registered with the channel with the given name as configured |
| Marc Nijdam |
3:475fae677f2d | 145 | * in the Helium Dashboard. |
| Marc Nijdam |
3:475fae677f2d | 146 | * |
| Marc Nijdam |
3:475fae677f2d | 147 | * The `result` value will be 0 if the channel was created |
| Marc Nijdam |
3:475fae677f2d | 148 | * successfully and non-`0` otherwise. |
| Marc Nijdam |
3:475fae677f2d | 149 | * |
| Marc Nijdam |
3:475fae677f2d | 150 | * @param name The name of the channel to authenticate with. |
| Marc Nijdam |
3:475fae677f2d | 151 | * @param result An out parameter for the result of the request. |
| Marc Nijdam |
3:475fae677f2d | 152 | */ |
| Marc Nijdam |
3:475fae677f2d | 153 | int begin(const char * name, int8_t * result); |
| Marc Nijdam |
3:475fae677f2d | 154 | |
| Marc Nijdam |
3:475fae677f2d | 155 | /** Send data to this channel. |
| Marc Nijdam |
3:475fae677f2d | 156 | * |
| Marc Nijdam |
3:475fae677f2d | 157 | * Send data to a given channel. The given data is sent to the |
| Marc Nijdam |
3:475fae677f2d | 158 | * configured channel and the result as returned by the channel is |
| Marc Nijdam |
3:475fae677f2d | 159 | * put in the `result` output variable. The result value is `0` |
| Marc Nijdam |
3:475fae677f2d | 160 | * for success and non-`0` if an error occurred. |
| Marc Nijdam |
3:475fae677f2d | 161 | * |
| Marc Nijdam |
3:475fae677f2d | 162 | * @note The maximum number of bytes that can be transmitted is |
| Marc Nijdam |
3:475fae677f2d | 163 | * limited to HELIUM_MAX_DATA_SIZE (about 100 bytes). |
| Marc Nijdam |
3:475fae677f2d | 164 | * |
| Marc Nijdam |
3:475fae677f2d | 165 | * @param data The data bytes to send |
| Marc Nijdam |
3:475fae677f2d | 166 | * @param len The number of bytes in data to send |
| Marc Nijdam |
3:475fae677f2d | 167 | * @param result An out parameter for the result returned by the channel |
| Marc Nijdam |
3:475fae677f2d | 168 | */ |
| Marc Nijdam |
3:475fae677f2d | 169 | int send(void const * data, size_t len, int8_t * result); |
| Marc Nijdam |
3:475fae677f2d | 170 | |
| Marc Nijdam |
3:475fae677f2d | 171 | /** Asynchronous begin method. |
| Marc Nijdam |
3:475fae677f2d | 172 | * |
| Marc Nijdam |
3:475fae677f2d | 173 | * The Channel#begin(const char *) method is a synchronous version |
| Marc Nijdam |
3:475fae677f2d | 174 | * of this method. Sending a request to a channel returns a |
| Marc Nijdam |
3:475fae677f2d | 175 | * `token` which can be used in a subsequent call to #poll() to |
| Marc Nijdam |
3:475fae677f2d | 176 | * check for results from the remote channel. |
| Marc Nijdam |
3:475fae677f2d | 177 | * |
| Marc Nijdam |
3:475fae677f2d | 178 | * @param name The name of the channel to authenticate with. |
| Marc Nijdam |
3:475fae677f2d | 179 | * @param token The output parameter for the pending result token. |
| Marc Nijdam |
3:475fae677f2d | 180 | */ |
| Marc Nijdam |
3:475fae677f2d | 181 | int begin(const char * name, uint16_t * token); |
| Marc Nijdam |
3:475fae677f2d | 182 | |
| Marc Nijdam |
3:475fae677f2d | 183 | /** Asynchornous send method. |
| Marc Nijdam |
3:475fae677f2d | 184 | * |
| Marc Nijdam |
3:475fae677f2d | 185 | * This is the asynchronous version of the #send(void const *data, |
| Marc Nijdam |
3:475fae677f2d | 186 | * size_t int8_t *) method. |
| Marc Nijdam |
3:475fae677f2d | 187 | * |
| Marc Nijdam |
3:475fae677f2d | 188 | * @param data The data bytes to send |
| Marc Nijdam |
3:475fae677f2d | 189 | * @param len The number of bytes in data to send |
| Marc Nijdam |
3:475fae677f2d | 190 | * @param token The output parameter for the pending result token |
| Marc Nijdam |
3:475fae677f2d | 191 | */ |
| Marc Nijdam |
3:475fae677f2d | 192 | int send(void const * data, size_t len, uint16_t * token); |
| Marc Nijdam |
3:475fae677f2d | 193 | |
| Marc Nijdam |
3:475fae677f2d | 194 | /** Poll for a result token. |
| Marc Nijdam |
3:475fae677f2d | 195 | * |
| Marc Nijdam |
3:475fae677f2d | 196 | * This polls the Helium Atom for the given number of retries for |
| Marc Nijdam |
3:475fae677f2d | 197 | * the result of a given `token`. Use HELIUM_POLL_RETRIES_5S for |
| Marc Nijdam |
3:475fae677f2d | 198 | * the recommended number of retries. |
| Marc Nijdam |
3:475fae677f2d | 199 | * |
| Marc Nijdam |
3:475fae677f2d | 200 | * If succcessful the result will be helium_status_OK and the |
| Marc Nijdam |
3:475fae677f2d | 201 | * result value will be set to the result of the original request |
| Marc Nijdam |
3:475fae677f2d | 202 | * that the token represents. |
| Marc Nijdam |
3:475fae677f2d | 203 | * |
| Marc Nijdam |
3:475fae677f2d | 204 | * @param token The token to check for |
| Marc Nijdam |
17:f38730193da3 | 205 | * @param result[out] The result of the given request token |
| Marc Nijdam |
3:475fae677f2d | 206 | * @param retries The number of times to retry |
| Marc Nijdam |
3:475fae677f2d | 207 | */ |
| Marc Nijdam |
17:f38730193da3 | 208 | int poll_result(uint16_t token, |
| Marc Nijdam |
17:f38730193da3 | 209 | int8_t * result, |
| Marc Nijdam |
17:f38730193da3 | 210 | uint32_t retries = HELIUM_POLL_RETRIES_5S); |
| Marc Nijdam |
17:f38730193da3 | 211 | |
| Marc Nijdam |
17:f38730193da3 | 212 | /** Poll for data on a channel. |
| Marc Nijdam |
17:f38730193da3 | 213 | * |
| Marc Nijdam |
17:f38730193da3 | 214 | * This polls the Helium Atom for the given number of retries for |
| Marc Nijdam |
20:d55e9eb828d4 | 215 | * any data on the channel. |
| Marc Nijdam |
17:f38730193da3 | 216 | * |
| Marc Nijdam |
17:f38730193da3 | 217 | * If successful the result will be helium_status_OK and the given |
| Marc Nijdam |
17:f38730193da3 | 218 | * `data` buffer will be filled with the received data. The `used` |
| Marc Nijdam |
17:f38730193da3 | 219 | * out parameter will be set to the number of bytes read. Note |
| Marc Nijdam |
17:f38730193da3 | 220 | * that the maximum number of bytes that can be sent is set by |
| Marc Nijdam |
17:f38730193da3 | 221 | * HELIUM_MAX_DATA_SIZE. |
| Marc Nijdam |
17:f38730193da3 | 222 | * |
| Marc Nijdam |
17:f38730193da3 | 223 | * @param[out] data The data buffer to fill with received data |
| Marc Nijdam |
17:f38730193da3 | 224 | * @param len The available length of the data buffer |
| Marc Nijdam |
17:f38730193da3 | 225 | * @param[out] used On success the number of bytes used up in data |
| Marc Nijdam |
17:f38730193da3 | 226 | * @param retries The number of times to retry |
| Marc Nijdam |
17:f38730193da3 | 227 | */ |
| Marc Nijdam |
20:d55e9eb828d4 | 228 | int poll_data(void * data, |
| Marc Nijdam |
17:f38730193da3 | 229 | size_t len, |
| Marc Nijdam |
17:f38730193da3 | 230 | size_t * used, |
| Marc Nijdam |
17:f38730193da3 | 231 | uint32_t retries = HELIUM_POLL_RETRIES_5S); |
| Marc Nijdam |
3:475fae677f2d | 232 | |
| Marc Nijdam |
23:cc2c1d1ed159 | 233 | /** The Helium Atom this channel uses to communicate. */ |
| Marc Nijdam |
23:cc2c1d1ed159 | 234 | Helium * helium; |
| Marc Nijdam |
23:cc2c1d1ed159 | 235 | |
| Marc Nijdam |
3:475fae677f2d | 236 | private: |
| Marc Nijdam |
3:475fae677f2d | 237 | int8_t _channel_id; |
| Marc Nijdam |
23:cc2c1d1ed159 | 238 | |
| Marc Nijdam |
23:cc2c1d1ed159 | 239 | friend class Config; |
| Marc Nijdam |
23:cc2c1d1ed159 | 240 | }; |
| Marc Nijdam |
23:cc2c1d1ed159 | 241 | |
| Marc Nijdam |
23:cc2c1d1ed159 | 242 | |
| Marc Nijdam |
23:cc2c1d1ed159 | 243 | enum config_poll_get_status |
| Marc Nijdam |
23:cc2c1d1ed159 | 244 | { |
| Marc Nijdam |
23:cc2c1d1ed159 | 245 | config_status_POLL_FOUND = 0, |
| Marc Nijdam |
23:cc2c1d1ed159 | 246 | config_status_POLL_FOUND_NULL = -1, |
| Marc Nijdam |
23:cc2c1d1ed159 | 247 | config_status_POLL_ERR_TYPE = -2, |
| Marc Nijdam |
3:475fae677f2d | 248 | }; |
| Marc Nijdam |
3:475fae677f2d | 249 | |
| Marc Nijdam |
23:cc2c1d1ed159 | 250 | |
| Marc Nijdam |
23:cc2c1d1ed159 | 251 | /** |
| Marc Nijdam |
23:cc2c1d1ed159 | 252 | * \class Config |
| Marc Nijdam |
23:cc2c1d1ed159 | 253 | * |
| Marc Nijdam |
23:cc2c1d1ed159 | 254 | * \brief A Channel Configuration |
| Marc Nijdam |
23:cc2c1d1ed159 | 255 | * |
| Marc Nijdam |
23:cc2c1d1ed159 | 256 | * Channels can have configuration data for the Helium Atom |
| Marc Nijdam |
23:cc2c1d1ed159 | 257 | * available. Depending on the IoT platform the configuration data is |
| Marc Nijdam |
23:cc2c1d1ed159 | 258 | * a representation of device configuration. Other terms used are |
| Marc Nijdam |
23:cc2c1d1ed159 | 259 | * device "twins" or "shadows". |
| Marc Nijdam |
23:cc2c1d1ed159 | 260 | * |
| Marc Nijdam |
23:cc2c1d1ed159 | 261 | * To use a channel configuration construct it with a channel that |
| Marc Nijdam |
23:cc2c1d1ed159 | 262 | * supports configuration and use the get methods to retrieve |
| Marc Nijdam |
23:cc2c1d1ed159 | 263 | * configuration values from the IoT platform's device |
| Marc Nijdam |
23:cc2c1d1ed159 | 264 | * representation. Use the set methods to set values in the IoT |
| Marc Nijdam |
23:cc2c1d1ed159 | 265 | * platform's representation of the device. |
| Marc Nijdam |
23:cc2c1d1ed159 | 266 | * |
| Marc Nijdam |
23:cc2c1d1ed159 | 267 | * Note that most IoT platforms represent sets and gets in different |
| Marc Nijdam |
23:cc2c1d1ed159 | 268 | * namespaces. The get methods represent the IoT platform's desired or |
| Marc Nijdam |
23:cc2c1d1ed159 | 269 | * expected namespace of the device, while the set methods are |
| Marc Nijdam |
23:cc2c1d1ed159 | 270 | * reflected in the actual, or current namespace of the device. |
| Marc Nijdam |
23:cc2c1d1ed159 | 271 | * |
| Marc Nijdam |
23:cc2c1d1ed159 | 272 | */ |
| Marc Nijdam |
23:cc2c1d1ed159 | 273 | class Config |
| Marc Nijdam |
23:cc2c1d1ed159 | 274 | { |
| Marc Nijdam |
23:cc2c1d1ed159 | 275 | public: |
| Marc Nijdam |
23:cc2c1d1ed159 | 276 | /** Construct a Configuration |
| Marc Nijdam |
23:cc2c1d1ed159 | 277 | * |
| Marc Nijdam |
23:cc2c1d1ed159 | 278 | * @param channel The channel to get/set configuration with |
| Marc Nijdam |
23:cc2c1d1ed159 | 279 | */ |
| Marc Nijdam |
23:cc2c1d1ed159 | 280 | Config(Channel * channel); |
| Marc Nijdam |
23:cc2c1d1ed159 | 281 | |
| Marc Nijdam |
23:cc2c1d1ed159 | 282 | /** Get an integer configuration value |
| Marc Nijdam |
23:cc2c1d1ed159 | 283 | * |
| Marc Nijdam |
23:cc2c1d1ed159 | 284 | * @param key The configuration key to get |
| Marc Nijdam |
23:cc2c1d1ed159 | 285 | * @param[out] value The target for the received value |
| Marc Nijdam |
23:cc2c1d1ed159 | 286 | * @param default_value The default value in case of errors |
| Marc Nijdam |
23:cc2c1d1ed159 | 287 | * @param retries The number of times to retry (optional) |
| Marc Nijdam |
23:cc2c1d1ed159 | 288 | * @returns 0 on success. If the result is > 0 the result code is |
| Marc Nijdam |
23:cc2c1d1ed159 | 289 | * one of the helium_status_ error codes. If the result is < 0 |
| Marc Nijdam |
23:cc2c1d1ed159 | 290 | * it is one of the config_poll_get_status error codes |
| Marc Nijdam |
23:cc2c1d1ed159 | 291 | */ |
| Marc Nijdam |
23:cc2c1d1ed159 | 292 | int get(const char * key, |
| Marc Nijdam |
23:cc2c1d1ed159 | 293 | int32_t * value, |
| Marc Nijdam |
23:cc2c1d1ed159 | 294 | int32_t default_value, |
| Marc Nijdam |
23:cc2c1d1ed159 | 295 | uint32_t retries = HELIUM_POLL_RETRIES_5S) |
| Marc Nijdam |
23:cc2c1d1ed159 | 296 | { |
| Marc Nijdam |
23:cc2c1d1ed159 | 297 | return _get(key, |
| Marc Nijdam |
23:cc2c1d1ed159 | 298 | helium_config_i32, |
| Marc Nijdam |
23:cc2c1d1ed159 | 299 | value, |
| Marc Nijdam |
23:cc2c1d1ed159 | 300 | sizeof(*value), |
| Marc Nijdam |
23:cc2c1d1ed159 | 301 | &default_value, |
| Marc Nijdam |
23:cc2c1d1ed159 | 302 | sizeof(default_value), |
| Marc Nijdam |
23:cc2c1d1ed159 | 303 | retries); |
| Marc Nijdam |
23:cc2c1d1ed159 | 304 | } |
| Marc Nijdam |
23:cc2c1d1ed159 | 305 | |
| Marc Nijdam |
23:cc2c1d1ed159 | 306 | /** Get a float configuration value |
| Marc Nijdam |
23:cc2c1d1ed159 | 307 | * |
| Marc Nijdam |
23:cc2c1d1ed159 | 308 | * @param key The configuration key to get |
| Marc Nijdam |
23:cc2c1d1ed159 | 309 | * @param[out] value The target for the received value |
| Marc Nijdam |
23:cc2c1d1ed159 | 310 | * @param default_value The default value in case of errors |
| Marc Nijdam |
23:cc2c1d1ed159 | 311 | * @param retries The number of times to retry (optional) |
| Marc Nijdam |
23:cc2c1d1ed159 | 312 | * @returns 0 on success. If the result is > 0 the result code is |
| Marc Nijdam |
23:cc2c1d1ed159 | 313 | * one of the helium_status_ error codes. If the result is < 0 |
| Marc Nijdam |
23:cc2c1d1ed159 | 314 | * it is one of the config_poll_get_status error codes |
| Marc Nijdam |
23:cc2c1d1ed159 | 315 | */ |
| Marc Nijdam |
23:cc2c1d1ed159 | 316 | int get(const char * key, |
| Marc Nijdam |
23:cc2c1d1ed159 | 317 | float * value, |
| Marc Nijdam |
23:cc2c1d1ed159 | 318 | float default_value, |
| Marc Nijdam |
23:cc2c1d1ed159 | 319 | uint32_t retries = HELIUM_POLL_RETRIES_5S) |
| Marc Nijdam |
23:cc2c1d1ed159 | 320 | { |
| Marc Nijdam |
23:cc2c1d1ed159 | 321 | return _get(key, |
| Marc Nijdam |
23:cc2c1d1ed159 | 322 | helium_config_f32, |
| Marc Nijdam |
23:cc2c1d1ed159 | 323 | value, |
| Marc Nijdam |
23:cc2c1d1ed159 | 324 | sizeof(*value), |
| Marc Nijdam |
23:cc2c1d1ed159 | 325 | &default_value, |
| Marc Nijdam |
23:cc2c1d1ed159 | 326 | sizeof(default_value), |
| Marc Nijdam |
23:cc2c1d1ed159 | 327 | retries); |
| Marc Nijdam |
23:cc2c1d1ed159 | 328 | } |
| Marc Nijdam |
23:cc2c1d1ed159 | 329 | |
| Marc Nijdam |
23:cc2c1d1ed159 | 330 | |
| Marc Nijdam |
23:cc2c1d1ed159 | 331 | /** Get a boolean configuration value |
| Marc Nijdam |
23:cc2c1d1ed159 | 332 | * |
| Marc Nijdam |
23:cc2c1d1ed159 | 333 | * @param key The configuration key to get |
| Marc Nijdam |
23:cc2c1d1ed159 | 334 | * @param[out] value The target for the received value |
| Marc Nijdam |
23:cc2c1d1ed159 | 335 | * @param default_value The default value in case of errors |
| Marc Nijdam |
23:cc2c1d1ed159 | 336 | * @param retries The number of times to retry (optional) |
| Marc Nijdam |
23:cc2c1d1ed159 | 337 | * @returns 0 on success. If the result is > 0 the result code is |
| Marc Nijdam |
23:cc2c1d1ed159 | 338 | * one of the helium_status_ error codes. If the result is < 0 |
| Marc Nijdam |
23:cc2c1d1ed159 | 339 | * it is one of the config_poll_get_status error codes |
| Marc Nijdam |
23:cc2c1d1ed159 | 340 | */ |
| Marc Nijdam |
23:cc2c1d1ed159 | 341 | int get(const char * key, |
| Marc Nijdam |
23:cc2c1d1ed159 | 342 | bool * value, |
| Marc Nijdam |
23:cc2c1d1ed159 | 343 | bool default_value, |
| Marc Nijdam |
23:cc2c1d1ed159 | 344 | uint32_t retries = HELIUM_POLL_RETRIES_5S) |
| Marc Nijdam |
23:cc2c1d1ed159 | 345 | { |
| Marc Nijdam |
23:cc2c1d1ed159 | 346 | return _get(key, |
| Marc Nijdam |
23:cc2c1d1ed159 | 347 | helium_config_bool, |
| Marc Nijdam |
23:cc2c1d1ed159 | 348 | value, |
| Marc Nijdam |
23:cc2c1d1ed159 | 349 | sizeof(*value), |
| Marc Nijdam |
23:cc2c1d1ed159 | 350 | &default_value, |
| Marc Nijdam |
23:cc2c1d1ed159 | 351 | sizeof(default_value), |
| Marc Nijdam |
23:cc2c1d1ed159 | 352 | retries); |
| Marc Nijdam |
23:cc2c1d1ed159 | 353 | } |
| Marc Nijdam |
23:cc2c1d1ed159 | 354 | |
| Marc Nijdam |
23:cc2c1d1ed159 | 355 | /** Get a string configuration value |
| Marc Nijdam |
23:cc2c1d1ed159 | 356 | * |
| Marc Nijdam |
23:cc2c1d1ed159 | 357 | * @param key The configuration key to get |
| Marc Nijdam |
23:cc2c1d1ed159 | 358 | * @param[out] value The target buffer for the received string |
| Marc Nijdam |
23:cc2c1d1ed159 | 359 | * @param value_len The length of the available buffer space |
| Marc Nijdam |
23:cc2c1d1ed159 | 360 | * @param default_value The default value to use if not found |
| Marc Nijdam |
23:cc2c1d1ed159 | 361 | * @param default_value_len The length of the default_value buffer. |
| Marc Nijdam |
23:cc2c1d1ed159 | 362 | * Note: Ensure to include the trailing NULL in this length |
| Marc Nijdam |
23:cc2c1d1ed159 | 363 | * parameter |
| Marc Nijdam |
23:cc2c1d1ed159 | 364 | * @param retries The number of times to retry (optional) |
| Marc Nijdam |
23:cc2c1d1ed159 | 365 | * @returns 0 on success. If the result is > 0 the result code is |
| Marc Nijdam |
23:cc2c1d1ed159 | 366 | * one of the helium_status_ error codes. If the result is < 0 |
| Marc Nijdam |
23:cc2c1d1ed159 | 367 | * it is one of the config_poll_get_status error codes |
| Marc Nijdam |
23:cc2c1d1ed159 | 368 | */ |
| Marc Nijdam |
23:cc2c1d1ed159 | 369 | int get(const char * key, |
| Marc Nijdam |
23:cc2c1d1ed159 | 370 | char * value, |
| Marc Nijdam |
23:cc2c1d1ed159 | 371 | size_t value_len, |
| Marc Nijdam |
23:cc2c1d1ed159 | 372 | char * default_value, |
| Marc Nijdam |
23:cc2c1d1ed159 | 373 | size_t default_value_len, |
| Marc Nijdam |
23:cc2c1d1ed159 | 374 | uint32_t retries = HELIUM_POLL_RETRIES_5S) |
| Marc Nijdam |
23:cc2c1d1ed159 | 375 | { |
| Marc Nijdam |
23:cc2c1d1ed159 | 376 | return _get(key, |
| Marc Nijdam |
23:cc2c1d1ed159 | 377 | helium_config_str, |
| Marc Nijdam |
23:cc2c1d1ed159 | 378 | value, |
| Marc Nijdam |
23:cc2c1d1ed159 | 379 | value_len, |
| Marc Nijdam |
23:cc2c1d1ed159 | 380 | default_value, |
| Marc Nijdam |
23:cc2c1d1ed159 | 381 | default_value_len, |
| Marc Nijdam |
23:cc2c1d1ed159 | 382 | retries); |
| Marc Nijdam |
23:cc2c1d1ed159 | 383 | } |
| Marc Nijdam |
23:cc2c1d1ed159 | 384 | |
| Marc Nijdam |
23:cc2c1d1ed159 | 385 | /** Send a request for a configuration value. |
| Marc Nijdam |
23:cc2c1d1ed159 | 386 | * |
| Marc Nijdam |
23:cc2c1d1ed159 | 387 | * Getting a configuration value requires sending a request with |
| Marc Nijdam |
23:cc2c1d1ed159 | 388 | * the configuration key and then using the resulting token in a |
| Marc Nijdam |
23:cc2c1d1ed159 | 389 | * #poll_get_result() call to wait for a response. |
| Marc Nijdam |
23:cc2c1d1ed159 | 390 | * |
| Marc Nijdam |
23:cc2c1d1ed159 | 391 | * @param key The configuration key to get |
| Marc Nijdam |
23:cc2c1d1ed159 | 392 | * @param[out] token The token representing the response. |
| Marc Nijdam |
23:cc2c1d1ed159 | 393 | * @returns 0 on success. One of the helium_status_ error |
| Marc Nijdam |
23:cc2c1d1ed159 | 394 | * codes otherwise. |
| Marc Nijdam |
23:cc2c1d1ed159 | 395 | */ |
| Marc Nijdam |
23:cc2c1d1ed159 | 396 | int get(const char * key, uint16_t * token); |
| Marc Nijdam |
23:cc2c1d1ed159 | 397 | |
| Marc Nijdam |
23:cc2c1d1ed159 | 398 | /** Poll the response of a configuration request. |
| Marc Nijdam |
23:cc2c1d1ed159 | 399 | * |
| Marc Nijdam |
23:cc2c1d1ed159 | 400 | * Polls the given token and validates any response against the |
| Marc Nijdam |
23:cc2c1d1ed159 | 401 | * given configuration key and expected type. If these match the |
| Marc Nijdam |
23:cc2c1d1ed159 | 402 | * value is copied into the given value buffer. |
| Marc Nijdam |
23:cc2c1d1ed159 | 403 | * |
| Marc Nijdam |
23:cc2c1d1ed159 | 404 | * Note: The short form methods for getting config values hide |
| Marc Nijdam |
23:cc2c1d1ed159 | 405 | * most of the complexity required to make a configuration get |
| Marc Nijdam |
23:cc2c1d1ed159 | 406 | * work. |
| Marc Nijdam |
23:cc2c1d1ed159 | 407 | * |
| Marc Nijdam |
23:cc2c1d1ed159 | 408 | * @param token The token returned from a previous #get() request |
| Marc Nijdam |
23:cc2c1d1ed159 | 409 | * @param config_key The configuration key to check for |
| Marc Nijdam |
23:cc2c1d1ed159 | 410 | * @param config_type The configuration type to check for |
| Marc Nijdam |
23:cc2c1d1ed159 | 411 | * @param[out] value The destination buffer to copy the result into |
| Marc Nijdam |
23:cc2c1d1ed159 | 412 | * @param value_len The size of the given destination buffer |
| Marc Nijdam |
23:cc2c1d1ed159 | 413 | * @param default_value The default value to use if not found |
| Marc Nijdam |
23:cc2c1d1ed159 | 414 | * @param default_value_len The length of the default_value buffer. |
| Marc Nijdam |
23:cc2c1d1ed159 | 415 | * @param retries The number of times to retry (optional) |
| Marc Nijdam |
23:cc2c1d1ed159 | 416 | * @param[out] result The channel response code. |
| Marc Nijdam |
23:cc2c1d1ed159 | 417 | * 0 for no errors, non-0 otherwise |
| Marc Nijdam |
23:cc2c1d1ed159 | 418 | * @returns 0 on success. If the result is > 0 the result code is |
| Marc Nijdam |
23:cc2c1d1ed159 | 419 | * one of the helium_status_ error codes. If the result is < 0 |
| Marc Nijdam |
23:cc2c1d1ed159 | 420 | * it is one of the config_poll_get_status error codes |
| Marc Nijdam |
23:cc2c1d1ed159 | 421 | */ |
| Marc Nijdam |
23:cc2c1d1ed159 | 422 | int poll_get_result(uint16_t token, |
| Marc Nijdam |
23:cc2c1d1ed159 | 423 | const char * config_key, |
| Marc Nijdam |
23:cc2c1d1ed159 | 424 | enum helium_config_type config_type, |
| Marc Nijdam |
23:cc2c1d1ed159 | 425 | void * value, |
| Marc Nijdam |
23:cc2c1d1ed159 | 426 | size_t value_len, |
| Marc Nijdam |
23:cc2c1d1ed159 | 427 | void * default_value, |
| Marc Nijdam |
23:cc2c1d1ed159 | 428 | size_t default_value_len, |
| Marc Nijdam |
23:cc2c1d1ed159 | 429 | int8_t * result, |
| Marc Nijdam |
23:cc2c1d1ed159 | 430 | uint32_t retries = HELIUM_POLL_RETRIES_5S); |
| Marc Nijdam |
23:cc2c1d1ed159 | 431 | |
| Marc Nijdam |
23:cc2c1d1ed159 | 432 | /** Set a float configuration value |
| Marc Nijdam |
23:cc2c1d1ed159 | 433 | * |
| Marc Nijdam |
23:cc2c1d1ed159 | 434 | * @param key The configuration key to set |
| Marc Nijdam |
23:cc2c1d1ed159 | 435 | * @param value The value to set |
| Marc Nijdam |
23:cc2c1d1ed159 | 436 | * @param retries The number of times to retry (optional) |
| Marc Nijdam |
23:cc2c1d1ed159 | 437 | * @returns 0 on success. One of the helium_status_ error |
| Marc Nijdam |
23:cc2c1d1ed159 | 438 | * codes otherwise. |
| Marc Nijdam |
23:cc2c1d1ed159 | 439 | */ |
| Marc Nijdam |
23:cc2c1d1ed159 | 440 | int set(const char * key, float value, uint32_t retries = HELIUM_POLL_RETRIES_5S) |
| Marc Nijdam |
23:cc2c1d1ed159 | 441 | { |
| Marc Nijdam |
23:cc2c1d1ed159 | 442 | return _set(key, helium_config_f32, &value, retries); |
| Marc Nijdam |
23:cc2c1d1ed159 | 443 | } |
| Marc Nijdam |
23:cc2c1d1ed159 | 444 | |
| Marc Nijdam |
23:cc2c1d1ed159 | 445 | /** Set an integer configuration value |
| Marc Nijdam |
23:cc2c1d1ed159 | 446 | * |
| Marc Nijdam |
23:cc2c1d1ed159 | 447 | * @param key The configuration key to set |
| Marc Nijdam |
23:cc2c1d1ed159 | 448 | * @param value The value to set |
| Marc Nijdam |
23:cc2c1d1ed159 | 449 | * @param retries The number of times to retry (optional) |
| Marc Nijdam |
23:cc2c1d1ed159 | 450 | * @returns 0 on success. One of the helium_status_ error |
| Marc Nijdam |
23:cc2c1d1ed159 | 451 | * codes otherwise. |
| Marc Nijdam |
23:cc2c1d1ed159 | 452 | */ |
| Marc Nijdam |
23:cc2c1d1ed159 | 453 | int set(const char * key, |
| Marc Nijdam |
23:cc2c1d1ed159 | 454 | int32_t value, |
| Marc Nijdam |
23:cc2c1d1ed159 | 455 | uint32_t retries = HELIUM_POLL_RETRIES_5S) |
| Marc Nijdam |
23:cc2c1d1ed159 | 456 | { |
| Marc Nijdam |
23:cc2c1d1ed159 | 457 | return _set(key, helium_config_i32, &value, retries); |
| Marc Nijdam |
23:cc2c1d1ed159 | 458 | } |
| Marc Nijdam |
23:cc2c1d1ed159 | 459 | |
| Marc Nijdam |
23:cc2c1d1ed159 | 460 | /** Set a boolean configuration value |
| Marc Nijdam |
23:cc2c1d1ed159 | 461 | * |
| Marc Nijdam |
23:cc2c1d1ed159 | 462 | * @param key The configuration key to set |
| Marc Nijdam |
23:cc2c1d1ed159 | 463 | * @param value The value to set |
| Marc Nijdam |
23:cc2c1d1ed159 | 464 | * @param retries The number of times to retry (optional) |
| Marc Nijdam |
23:cc2c1d1ed159 | 465 | * @returns 0 on success. One of the helium_status_ error |
| Marc Nijdam |
23:cc2c1d1ed159 | 466 | * codes otherwise. |
| Marc Nijdam |
23:cc2c1d1ed159 | 467 | */ |
| Marc Nijdam |
23:cc2c1d1ed159 | 468 | int set(const char * key, bool value, uint32_t retries = HELIUM_POLL_RETRIES_5S) |
| Marc Nijdam |
23:cc2c1d1ed159 | 469 | { |
| Marc Nijdam |
23:cc2c1d1ed159 | 470 | return _set(key, helium_config_bool, &value, retries); |
| Marc Nijdam |
23:cc2c1d1ed159 | 471 | } |
| Marc Nijdam |
23:cc2c1d1ed159 | 472 | |
| Marc Nijdam |
23:cc2c1d1ed159 | 473 | /** Set a string configuration value |
| Marc Nijdam |
23:cc2c1d1ed159 | 474 | * |
| Marc Nijdam |
23:cc2c1d1ed159 | 475 | * @param key The configuration key to set |
| Marc Nijdam |
23:cc2c1d1ed159 | 476 | * @param value The value to set |
| Marc Nijdam |
23:cc2c1d1ed159 | 477 | * @param retries The number of times to retry (optional) |
| Marc Nijdam |
23:cc2c1d1ed159 | 478 | * @returns 0 on success. One of the helium_status_ error |
| Marc Nijdam |
23:cc2c1d1ed159 | 479 | * codes otherwise. |
| Marc Nijdam |
23:cc2c1d1ed159 | 480 | */ |
| Marc Nijdam |
23:cc2c1d1ed159 | 481 | int set(const char * key, |
| Marc Nijdam |
23:cc2c1d1ed159 | 482 | const char * value, |
| Marc Nijdam |
23:cc2c1d1ed159 | 483 | uint32_t retries = HELIUM_POLL_RETRIES_5S) |
| Marc Nijdam |
23:cc2c1d1ed159 | 484 | { |
| Marc Nijdam |
23:cc2c1d1ed159 | 485 | return _set(key, helium_config_str, &value, retries); |
| Marc Nijdam |
23:cc2c1d1ed159 | 486 | } |
| Marc Nijdam |
23:cc2c1d1ed159 | 487 | |
| Marc Nijdam |
23:cc2c1d1ed159 | 488 | /** Set a null configuration value |
| Marc Nijdam |
23:cc2c1d1ed159 | 489 | * |
| Marc Nijdam |
23:cc2c1d1ed159 | 490 | * @param key The configuration key to set |
| Marc Nijdam |
23:cc2c1d1ed159 | 491 | * @param retries The number of times to retry (optional) |
| Marc Nijdam |
23:cc2c1d1ed159 | 492 | * @returns 0 on success. One of the helium_status_ error |
| Marc Nijdam |
23:cc2c1d1ed159 | 493 | * codes otherwise. |
| Marc Nijdam |
23:cc2c1d1ed159 | 494 | */ |
| Marc Nijdam |
23:cc2c1d1ed159 | 495 | int set_null(const char * key, uint32_t retries = HELIUM_POLL_RETRIES_5S) |
| Marc Nijdam |
23:cc2c1d1ed159 | 496 | { |
| Marc Nijdam |
23:cc2c1d1ed159 | 497 | return _set(key, helium_config_null, NULL, retries); |
| Marc Nijdam |
23:cc2c1d1ed159 | 498 | } |
| Marc Nijdam |
23:cc2c1d1ed159 | 499 | |
| Marc Nijdam |
23:cc2c1d1ed159 | 500 | /** Send a request for setting a configuration value. |
| Marc Nijdam |
23:cc2c1d1ed159 | 501 | * |
| Marc Nijdam |
23:cc2c1d1ed159 | 502 | * Setting a configuration value requires sending a request with |
| Marc Nijdam |
23:cc2c1d1ed159 | 503 | * the configuration key, the value type and the value and then |
| Marc Nijdam |
23:cc2c1d1ed159 | 504 | * using the resulting token in a #poll_set_result() call to wait |
| Marc Nijdam |
23:cc2c1d1ed159 | 505 | * for a response. |
| Marc Nijdam |
23:cc2c1d1ed159 | 506 | * |
| Marc Nijdam |
23:cc2c1d1ed159 | 507 | * @param key The configuration key to set |
| Marc Nijdam |
23:cc2c1d1ed159 | 508 | * @param value_type The type of the configuration value to set |
| Marc Nijdam |
23:cc2c1d1ed159 | 509 | * @param value A pointer to the value that needs to be st |
| Marc Nijdam |
23:cc2c1d1ed159 | 510 | * @param[out] token The token representing the response. |
| Marc Nijdam |
23:cc2c1d1ed159 | 511 | * @returns 0 on success. One of the helium_status_ error |
| Marc Nijdam |
23:cc2c1d1ed159 | 512 | * codes otherwise. |
| Marc Nijdam |
23:cc2c1d1ed159 | 513 | */ |
| Marc Nijdam |
23:cc2c1d1ed159 | 514 | int set(const char * key, |
| Marc Nijdam |
23:cc2c1d1ed159 | 515 | helium_config_type value_type, |
| Marc Nijdam |
23:cc2c1d1ed159 | 516 | void * value, |
| Marc Nijdam |
23:cc2c1d1ed159 | 517 | uint16_t * token); |
| Marc Nijdam |
23:cc2c1d1ed159 | 518 | |
| Marc Nijdam |
23:cc2c1d1ed159 | 519 | /** Poll the response of a configuration set request. |
| Marc Nijdam |
23:cc2c1d1ed159 | 520 | * |
| Marc Nijdam |
23:cc2c1d1ed159 | 521 | * Polls the given token and returns the result code of the set |
| Marc Nijdam |
23:cc2c1d1ed159 | 522 | * request. |
| Marc Nijdam |
23:cc2c1d1ed159 | 523 | * |
| Marc Nijdam |
23:cc2c1d1ed159 | 524 | * Note: The short form methods for getting config values hide |
| Marc Nijdam |
23:cc2c1d1ed159 | 525 | * most of the complexity required to make a configuration get |
| Marc Nijdam |
23:cc2c1d1ed159 | 526 | * work. |
| Marc Nijdam |
23:cc2c1d1ed159 | 527 | * |
| Marc Nijdam |
23:cc2c1d1ed159 | 528 | * @param token The token returned from a previous #set() request |
| Marc Nijdam |
23:cc2c1d1ed159 | 529 | * @param[out] result A pointer to storage for the response code |
| Marc Nijdam |
23:cc2c1d1ed159 | 530 | * @param retries The number of times to retry (optional) |
| Marc Nijdam |
23:cc2c1d1ed159 | 531 | * @returns A helium_status result code for the actual |
| Marc Nijdam |
23:cc2c1d1ed159 | 532 | * communication part. If the result is helium_status_OK, the |
| Marc Nijdam |
23:cc2c1d1ed159 | 533 | * result code can be used to check if the set was |
| Marc Nijdam |
23:cc2c1d1ed159 | 534 | * successful. The result code will be 0 on success, and |
| Marc Nijdam |
23:cc2c1d1ed159 | 535 | * non-zero otherwise. |
| Marc Nijdam |
23:cc2c1d1ed159 | 536 | */ |
| Marc Nijdam |
23:cc2c1d1ed159 | 537 | int poll_set_result(uint16_t token, |
| Marc Nijdam |
23:cc2c1d1ed159 | 538 | int8_t * result, |
| Marc Nijdam |
23:cc2c1d1ed159 | 539 | uint32_t retries = HELIUM_POLL_RETRIES_5S); |
| Marc Nijdam |
23:cc2c1d1ed159 | 540 | |
| Marc Nijdam |
23:cc2c1d1ed159 | 541 | /** Check whether configuration values are stale. |
| Marc Nijdam |
23:cc2c1d1ed159 | 542 | * |
| Marc Nijdam |
23:cc2c1d1ed159 | 543 | * Checks whether there has been a system indication that |
| Marc Nijdam |
23:cc2c1d1ed159 | 544 | * configuration attributes may have gone stale. |
| Marc Nijdam |
23:cc2c1d1ed159 | 545 | * |
| Marc Nijdam |
23:cc2c1d1ed159 | 546 | * When this returns true you should assume that any configuration |
| Marc Nijdam |
23:cc2c1d1ed159 | 547 | * values you have previously retrieved are no longer valid. |
| Marc Nijdam |
23:cc2c1d1ed159 | 548 | * |
| Marc Nijdam |
23:cc2c1d1ed159 | 549 | * @returns true if previous configuration values are stale, false |
| Marc Nijdam |
23:cc2c1d1ed159 | 550 | * if not |
| Marc Nijdam |
23:cc2c1d1ed159 | 551 | */ |
| Marc Nijdam |
23:cc2c1d1ed159 | 552 | bool is_stale(); |
| Marc Nijdam |
23:cc2c1d1ed159 | 553 | |
| Marc Nijdam |
23:cc2c1d1ed159 | 554 | |
| Marc Nijdam |
23:cc2c1d1ed159 | 555 | private: |
| Marc Nijdam |
23:cc2c1d1ed159 | 556 | int _get(const char * config_key, |
| Marc Nijdam |
23:cc2c1d1ed159 | 557 | enum helium_config_type config_type, |
| Marc Nijdam |
23:cc2c1d1ed159 | 558 | void * value, |
| Marc Nijdam |
23:cc2c1d1ed159 | 559 | size_t value_len, |
| Marc Nijdam |
23:cc2c1d1ed159 | 560 | void * default_value, |
| Marc Nijdam |
23:cc2c1d1ed159 | 561 | size_t default_value_len, |
| Marc Nijdam |
23:cc2c1d1ed159 | 562 | uint32_t retries); |
| Marc Nijdam |
23:cc2c1d1ed159 | 563 | int _set(const char * config_key, |
| Marc Nijdam |
23:cc2c1d1ed159 | 564 | enum helium_config_type value_type, |
| Marc Nijdam |
23:cc2c1d1ed159 | 565 | void * value, |
| Marc Nijdam |
23:cc2c1d1ed159 | 566 | uint32_t retries); |
| Marc Nijdam |
23:cc2c1d1ed159 | 567 | Channel * _channel; |
| Marc Nijdam |
23:cc2c1d1ed159 | 568 | }; |
| Marc Nijdam |
23:cc2c1d1ed159 | 569 | |
| Marc Nijdam |
23:cc2c1d1ed159 | 570 | |
| Marc Nijdam |
3:475fae677f2d | 571 | #endif // HELIUM_H |