Skip to content

Commit 068d92d

Browse files
sellensrsellensr
committed
Doxify AdafruitIO.h, AdafruitIO.cpp
Briefs could be expanded, but it's a start. Reordered to put instatiation, initialization, destruction together. No code changes.
1 parent 0edd235 commit 068d92d

2 files changed

Lines changed: 205 additions & 64 deletions

File tree

‎src/AdafruitIO.cpp‎

Lines changed: 186 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,16 @@
1111
//
1212
#include "AdafruitIO.h"
1313

14+
/**************************************************************************/
15+
/*!
16+
@brief Instantiate the AIO object.
17+
@param user
18+
A pointer to a constant AIO user name.
19+
@param key
20+
A pointer to a constant key for the user name.
21+
@return none
22+
*/
23+
/**************************************************************************/
1424
AdafruitIO::AdafruitIO(const char *user, const char *key)
1525
{
1626
_mqtt = 0;
@@ -27,6 +37,83 @@ AdafruitIO::AdafruitIO(const char *user, const char *key)
2737
_init();
2838
}
2939

40+
/**************************************************************************/
41+
/*!
42+
@brief Initialize the AIO object.
43+
@return none
44+
*/
45+
/**************************************************************************/
46+
void AdafruitIO::_init()
47+
{
48+
49+
// we have never pinged, so set last ping to now
50+
_last_ping = millis();
51+
52+
// dynamically allocate memory for err topic
53+
_err_topic = (char *)malloc(sizeof(char) * (strlen(_username) + strlen(AIO_ERROR_TOPIC) + 1));
54+
55+
if(_err_topic) {
56+
57+
// build error topic
58+
strcpy(_err_topic, _username);
59+
strcat(_err_topic, AIO_ERROR_TOPIC);
60+
61+
} else {
62+
63+
// malloc failed
64+
_err_topic = 0;
65+
66+
}
67+
68+
// dynamically allocate memory for throttle topic
69+
_throttle_topic = (char *)malloc(sizeof(char) * (strlen(_username) + strlen(AIO_THROTTLE_TOPIC) + 1));
70+
71+
if(_throttle_topic) {
72+
73+
// build throttle topic
74+
strcpy(_throttle_topic, _username);
75+
strcat(_throttle_topic, AIO_THROTTLE_TOPIC);
76+
77+
} else {
78+
79+
// malloc failed
80+
_throttle_topic = 0;
81+
82+
}
83+
84+
}
85+
86+
/**************************************************************************/
87+
/*!
88+
@brief Destructor to end the AIO object.
89+
@return none
90+
*/
91+
/**************************************************************************/
92+
AdafruitIO::~AdafruitIO()
93+
{
94+
if(_err_topic)
95+
free(_err_topic);
96+
97+
if(_throttle_topic)
98+
free(_throttle_topic);
99+
100+
if(_err_sub)
101+
delete _err_sub;
102+
103+
if(_throttle_sub)
104+
delete _throttle_sub;
105+
}
106+
107+
/**************************************************************************/
108+
/*!
109+
@brief Prints errors
110+
@param err
111+
An error string to print.
112+
@param len
113+
The length of the error string.
114+
@return none
115+
*/
116+
/**************************************************************************/
30117
void errorCallback(char *err, uint16_t len)
31118
{
32119
AIO_ERROR_PRINTLN();
@@ -35,6 +122,13 @@ void errorCallback(char *err, uint16_t len)
35122
AIO_ERROR_PRINTLN();
36123
}
37124

125+
/**************************************************************************/
126+
/*!
127+
@brief Connects to AIO, setting up using parameters set when the
128+
class is instantiated.
129+
@return none
130+
*/
131+
/**************************************************************************/
38132
void AdafruitIO::connect()
39133
{
40134

@@ -62,21 +156,17 @@ void AdafruitIO::connect()
62156

63157
}
64158

65-
AdafruitIO::~AdafruitIO()
66-
{
67-
if(_err_topic)
68-
free(_err_topic);
69-
70-
if(_throttle_topic)
71-
free(_throttle_topic);
72-
73-
if(_err_sub)
74-
delete _err_sub;
75-
76-
if(_throttle_sub)
77-
delete _throttle_sub;
78-
}
79159

160+
/**************************************************************************/
161+
/*!
162+
@brief Create a new AIO feed.
163+
@param name
164+
The AIO name of the feed.
165+
@param owner
166+
The AIO name of the user that owns the feed, if not the current user.
167+
@return A pointer to the feed.
168+
*/
169+
/**************************************************************************/
80170
AdafruitIO_Feed* AdafruitIO::feed(const char* name)
81171
{
82172
return new AdafruitIO_Feed(this, name);
@@ -87,61 +177,54 @@ AdafruitIO_Feed* AdafruitIO::feed(const char* name, const char* owner)
87177
return new AdafruitIO_Feed(this, name, owner);
88178
}
89179

180+
/**************************************************************************/
181+
/*!
182+
@brief Create a new AIO time.
183+
@param format
184+
A format specifier.
185+
@return A pointer to the time.
186+
*/
187+
/**************************************************************************/
90188
AdafruitIO_Time* AdafruitIO::time(aio_time_format_t format)
91189
{
92190
return new AdafruitIO_Time(this, format);
93191
}
94192

193+
/**************************************************************************/
194+
/*!
195+
@brief Create a new AIO group.
196+
@param name
197+
The AIO name of the group.
198+
@return A pointer to the group.
199+
*/
200+
/**************************************************************************/
95201
AdafruitIO_Group* AdafruitIO::group(const char* name)
96202
{
97203
return new AdafruitIO_Group(this, name);
98204
}
99205

206+
/**************************************************************************/
207+
/*!
208+
@brief Create a new AIO dashboard.
209+
@param name
210+
The AIO name of the dashboard.
211+
@return A pointer to the dashboard.
212+
*/
213+
/**************************************************************************/
100214
AdafruitIO_Dashboard* AdafruitIO::dashboard(const char* name)
101215
{
102216
return new AdafruitIO_Dashboard(this, name);
103217
}
104218

105-
void AdafruitIO::_init()
106-
{
107-
108-
// we have never pinged, so set last ping to now
109-
_last_ping = millis();
110-
111-
// dynamically allocate memory for err topic
112-
_err_topic = (char *)malloc(sizeof(char) * (strlen(_username) + strlen(AIO_ERROR_TOPIC) + 1));
113-
114-
if(_err_topic) {
115-
116-
// build error topic
117-
strcpy(_err_topic, _username);
118-
strcat(_err_topic, AIO_ERROR_TOPIC);
119-
120-
} else {
121-
122-
// malloc failed
123-
_err_topic = 0;
124-
125-
}
126-
127-
// dynamically allocate memory for throttle topic
128-
_throttle_topic = (char *)malloc(sizeof(char) * (strlen(_username) + strlen(AIO_THROTTLE_TOPIC) + 1));
129-
130-
if(_throttle_topic) {
131-
132-
// build throttle topic
133-
strcpy(_throttle_topic, _username);
134-
strcat(_throttle_topic, AIO_THROTTLE_TOPIC);
135-
136-
} else {
137-
138-
// malloc failed
139-
_throttle_topic = 0;
140-
141-
}
142-
143-
}
144219

220+
/**************************************************************************/
221+
/*!
222+
@brief Provide status explanation strings.
223+
@param _status
224+
The AIO status value
225+
@return A pointer to the status string.
226+
*/
227+
/**************************************************************************/
145228
const __FlashStringHelper* AdafruitIO::statusText()
146229
{
147230
switch(_status) {
@@ -169,6 +252,16 @@ const __FlashStringHelper* AdafruitIO::statusText()
169252
}
170253
}
171254

255+
/**************************************************************************/
256+
/*!
257+
@brief Must be called frequently to keep AIO connections alive.
258+
@param busywait_ms
259+
The packet read timeout, optional.
260+
@param fail_fast
261+
Set true to skip retries and return with status immediately, optional.
262+
@return AIO status value
263+
*/
264+
/**************************************************************************/
172265
aio_status_t AdafruitIO::run(uint16_t busywait_ms, bool fail_fast)
173266
{
174267
uint32_t timeStart = millis();
@@ -205,6 +298,13 @@ aio_status_t AdafruitIO::run(uint16_t busywait_ms, bool fail_fast)
205298
return status();
206299
}
207300

301+
/**************************************************************************/
302+
/*!
303+
@brief Status check.
304+
@return An AIO status value. Lower values represent poorer connection
305+
status.
306+
*/
307+
/**************************************************************************/
208308
aio_status_t AdafruitIO::status()
209309
{
210310
aio_status_t net_status = networkStatus();
@@ -220,22 +320,46 @@ aio_status_t AdafruitIO::status()
220320
return _status;
221321
}
222322

323+
/**************************************************************************/
324+
/*!
325+
@brief Identify the board.
326+
@return A board ID
327+
*/
328+
/**************************************************************************/
223329
char* AdafruitIO::boardID()
224330
{
225331
return AdafruitIO_Board::id();
226332
}
227333

334+
/**************************************************************************/
335+
/*!
336+
@brief Identify the board type.
337+
@return A board type
338+
*/
339+
/**************************************************************************/
228340
const char* AdafruitIO::boardType()
229341
{
230342
return AdafruitIO_Board::type();
231343
}
232344

345+
/**************************************************************************/
346+
/*!
347+
@brief Identify the software version.
348+
@return A pointer to a version number string.
349+
*/
350+
/**************************************************************************/
233351
char* AdafruitIO::version()
234352
{
235353
sprintf(_version, "%d.%d.%d", ADAFRUITIO_VERSION_MAJOR, ADAFRUITIO_VERSION_MINOR, ADAFRUITIO_VERSION_PATCH);
236354
return _version;
237355
}
238356

357+
/**************************************************************************/
358+
/*!
359+
@brief Identify the user agent.
360+
@return A pointer to a user agent string.
361+
*/
362+
/**************************************************************************/
239363
char* AdafruitIO::userAgent()
240364
{
241365
if(!_user_agent) {
@@ -251,6 +375,15 @@ char* AdafruitIO::userAgent()
251375
return _user_agent;
252376
}
253377

378+
/**************************************************************************/
379+
/*!
380+
@brief MQTT status check.
381+
@param fail_fast
382+
Set true to skip retries and return with status immediately, optional.
383+
@return An MQTT status value. Lower values represent poorer connection
384+
status.
385+
*/
386+
/**************************************************************************/
254387
aio_status_t AdafruitIO::mqttStatus(bool fail_fast)
255388
{
256389
// if the connection failed,

‎src/AdafruitIO.h‎

Lines changed: 19 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,17 @@
1-
//
2-
// Adafruit invests time and resources providing this open source code.
3-
// Please support Adafruit and open source hardware by purchasing
4-
// products from Adafruit!
5-
//
6-
// Copyright (c) 2015-2016 Adafruit Industries
7-
// Authors: Tony DiCola, Todd Treece
8-
// Licensed under the MIT license.
9-
//
10-
// All text above must be included in any redistribution.
11-
//
1+
/*!
2+
* @file AdafruitIO.h
3+
*
4+
* Adafruit invests time and resources providing this open source code.
5+
* Please support Adafruit and open source hardware by purchasing
6+
* products from Adafruit!
7+
*
8+
* Copyright (c) 2015-2016 Adafruit Industries
9+
* Authors: Tony DiCola, Todd Treece
10+
* Licensed under the MIT license.
11+
*
12+
* All text above must be included in any redistribution.
13+
*/
14+
1215
#ifndef ADAFRUITIO_H
1316
#define ADAFRUITIO_H
1417

@@ -32,6 +35,11 @@
3235
#endif
3336

3437

38+
/**************************************************************************/
39+
/*!
40+
@brief Class for interacting with adafruit.io (AIO)
41+
*/
42+
/**************************************************************************/
3543
class AdafruitIO {
3644

3745
friend class AdafruitIO_Feed;

0 commit comments

Comments
 (0)