Skip to content

Commit b6f9f6b

Browse files
aufdenkampeaufdenkampe
committed
Additional upddates to style & doc conventions of >0.25
@dnowacki-usgs, I made these edits while taking my first look at your code. Thanks!!! The timing is good, since I'm also working on another publisher with EnviroDIY#324. My edits should only be to whitespace and doxygen-formated comments, so it should work identically to what you submitted. Can you confirm?
1 parent 4277fff commit b6f9f6b

File tree

2 files changed

+186
-49
lines changed

2 files changed

+186
-49
lines changed

‎src/publishers/HologramPublisher.cpp‎

Lines changed: 16 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22
* @file HologramPublisher.cpp
33
* @copyright 2020 Stroud Water Research Center
44
* Part of the EnviroDIY ModularSensors library for Arduino
5+
* @author Dan Nowacki <[email protected]>
56
* @author Sara Geleskie Damiano <[email protected]>
67
*
78
* @brief Implements the HologramPublisher class.
@@ -21,22 +22,29 @@ const char* HologramPublisher::postEndpoint = "/api/1/csr/data/";
2122
const char* HologramPublisher::hologramHost = "cloudsocket.hologram.io";
2223
const int HologramPublisher::hologramPort = 9999;
2324
const char* HologramPublisher::authHeader = "\r\nAuthorization: Basic ";
25+
//
26+
//
27+
//
2428
const char* HologramPublisher::contentLengthHeader = "\r\nContent-Length: ";
25-
const char* HologramPublisher::contentTypeHeader = "\r\nContent-Type: application/json\r\n\r\n";
29+
const char* HologramPublisher::contentTypeHeader =
30+
"\r\nContent-Type: application/json\r\n\r\n";
2631

2732
const char* HologramPublisher::deviceIdTag = "{\"deviceid\":";
2833
const char* HologramPublisher::bodyTag = ",\"body\":\"";
29-
const char* HologramPublisher::deviceId = "xxxxxx"; // enter 6-digit Hologram device ID here
34+
const char* HologramPublisher::deviceId = "xxxxxx";
35+
// enter 6-digit Hologram device ID here
3036

3137

3238
// Constructors
3339
HologramPublisher::HologramPublisher() : dataPublisher() {
3440
// MS_DBG(F("dataPublisher object created"));
41+
_registrationToken = NULL;
3542
}
3643
HologramPublisher::HologramPublisher(Logger& baseLogger, uint8_t sendEveryX,
3744
uint8_t sendOffset)
3845
: dataPublisher(baseLogger, sendEveryX, sendOffset) {
3946
// MS_DBG(F("dataPublisher object created"));
47+
_registrationToken = NULL;
4048
}
4149
HologramPublisher::HologramPublisher(Logger& baseLogger, Client* inClient,
4250
uint8_t sendEveryX, uint8_t sendOffset)
@@ -72,8 +80,7 @@ void HologramPublisher::setToken(const char* registrationToken) {
7280

7381

7482
// Calculates how long the JSON will be
75-
uint16_t HologramPublisher::calculateJsonSize()
76-
{
83+
uint16_t HologramPublisher::calculateJsonSize() {
7784
uint16_t jsonLength = 12; // {"deviceid":
7885
jsonLength += 6; // six-digit device ID
7986
jsonLength += 10; // ","body":"
@@ -114,8 +121,7 @@ uint16_t HologramPublisher::calculatePostSize()
114121

115122

116123
// This prints a properly formatted JSON for EnviroDIY to an Arduino stream
117-
void HologramPublisher::printSensorDataJSON(Stream *stream)
118-
{
124+
void HologramPublisher::printSensorDataJSON(Stream* stream) {
119125
stream->print(deviceIdTag);
120126
stream->print(deviceId);
121127
stream->print(bodyTag);
@@ -136,8 +142,7 @@ void HologramPublisher::printSensorDataJSON(Stream *stream)
136142

137143
// This prints a fully structured post request for EnviroDIY to the
138144
// specified stream.
139-
void HologramPublisher::printEnviroDIYRequest(Stream *stream)
140-
{
145+
void HologramPublisher::printEnviroDIYRequest(Stream* stream) {
141146
// Stream the HTTP headers for the post request
142147
stream->print(postHeader);
143148
stream->print(postEndpoint);
@@ -160,16 +165,14 @@ void HologramPublisher::printEnviroDIYRequest(Stream *stream)
160165
// A way to begin with everything already set
161166
void HologramPublisher::begin(Logger& baseLogger, Client* inClient,
162167
const char* registrationToken,
163-
const char* samplingFeatureUUID)
164-
{
168+
const char* samplingFeatureUUID) {
165169
setToken(registrationToken);
166170
dataPublisher::begin(baseLogger, inClient);
167171
_baseLogger->setSamplingFeatureUUID(samplingFeatureUUID);
168172
}
169173
void HologramPublisher::begin(Logger& baseLogger,
170174
const char* registrationToken,
171-
const char* samplingFeatureUUID)
172-
{
175+
const char* samplingFeatureUUID) {
173176
setToken(registrationToken);
174177
dataPublisher::begin(baseLogger);
175178
_baseLogger->setSamplingFeatureUUID(samplingFeatureUUID);
@@ -181,8 +184,7 @@ void HologramPublisher::begin(Logger& baseLogger,
181184
// over that connection.
182185
// The return is the http status code of the response.
183186
// int16_t HologramPublisher::postDataEnviroDIY(void)
184-
int16_t HologramPublisher::publishData(Client* outClient)
185-
{
187+
int16_t HologramPublisher::publishData(Client* outClient) {
186188
// Create a buffer for the portions of the request and response
187189
char tempBuffer[37] = "";
188190
uint16_t did_respond = 0;

‎src/publishers/HologramPublisher.h‎

Lines changed: 170 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22
* @file HologramPublisher.h
33
* @copyright 2020 Stroud Water Research Center
44
* Part of the EnviroDIY ModularSensors library for Arduino
5+
* @author Dan Nowacki <[email protected]>
56
* @author Sara Geleskie Damiano <[email protected]>
67
*
78
* @brief Contains the HologramPublisher subclass of dataPublisher for
@@ -28,64 +29,192 @@
2829
// ============================================================================
2930
// Functions for the EnviroDIY data portal receivers.
3031
// ============================================================================
32+
/**
33+
* @brief The HologramPublisher subclass of dataPublisher for publishing data
34+
* to the Hologram API, https://www.hologram.io/references/http
35+
*/
3136
class HologramPublisher : public dataPublisher {
3237
public:
3338
// Constructors
3439
/**
3540
* @brief Construct a new Hologram Publisher object with no members set.
3641
*/
3742
HologramPublisher();
38-
HologramPublisher(Logger& baseLogger,
39-
uint8_t sendEveryX = 1, uint8_t sendOffset = 0);
40-
HologramPublisher(Logger& baseLogger, Client *inClient,
41-
uint8_t sendEveryX = 1, uint8_t sendOffset = 0);
42-
HologramPublisher(Logger& baseLogger,
43-
const char *registrationToken,
44-
const char *samplingFeatureUUID,
45-
uint8_t sendEveryX = 1, uint8_t sendOffset = 0);
46-
HologramPublisher(Logger& baseLogger, Client *inClient,
47-
const char *registrationToken,
48-
const char *samplingFeatureUUID,
43+
/**
44+
* @brief Construct a new Hologram Publisher object
45+
*
46+
* @note If a client is never specified, the publisher will attempt to
47+
* create and use a client on a LoggerModem instance tied to the attached
48+
* logger.
49+
*
50+
* @param baseLogger The logger supplying the data to be published
51+
* @param sendEveryX Currently unimplemented, intended for future use to
52+
* enable caching and bulk publishing
53+
* @param sendOffset Currently unimplemented, intended for future use to
54+
* enable publishing data at a time slightly delayed from when it is
55+
* collected
56+
*
57+
* @note It is possible (though very unlikey) that using this constructor
58+
* could cause errors if the compiler attempts to initialize the publisher
59+
* instance before the logger instance. If you suspect you are seeing that
60+
* issue, use the null constructor and a populated begin(...) within your
61+
* set-up function.
62+
*/
63+
explicit HologramPublisher(Logger& baseLogger, uint8_t sendEveryX = 1,
64+
uint8_t sendOffset = 0);
65+
/**
66+
* @brief Construct a new Hologram Publisher object
67+
*
68+
* @param baseLogger The logger supplying the data to be published
69+
* @param inClient An Arduino client instance to use to print data to.
70+
* Allows the use of any type of client and multiple clients tied to a
71+
* single TinyGSM modem instance
72+
* @param sendEveryX Currently unimplemented, intended for future use to
73+
* enable caching and bulk publishing
74+
* @param sendOffset Currently unimplemented, intended for future use to
75+
* enable publishing data at a time slightly delayed from when it is
76+
* collected
77+
*
78+
* @note It is possible (though very unlikey) that using this constructor
79+
* could cause errors if the compiler attempts to initialize the publisher
80+
* instance before the logger instance. If you suspect you are seeing that
81+
* issue, use the null constructor and a populated begin(...) within your
82+
* set-up function.
83+
*/
84+
HologramPublisher(Logger& baseLogger, Client* inClient,
4985
uint8_t sendEveryX = 1, uint8_t sendOffset = 0);
50-
// Destructor
86+
/**
87+
* @brief Construct a new Hologram Publisher object
88+
*
89+
* @param baseLogger The logger supplying the data to be published
90+
* @param registrationToken The registration token for the site on the
91+
* Monitor My Watershed data portal.
92+
* @param samplingFeatureUUID The sampling feature UUID for the site on the
93+
* Monitor My Watershed data portal.
94+
* @param sendEveryX Currently unimplemented, intended for future use to
95+
* enable caching and bulk publishing
96+
* @param sendOffset Currently unimplemented, intended for future use to
97+
* enable publishing data at a time slightly delayed from when it is
98+
* collected
99+
*/
100+
HologramPublisher(Logger& baseLogger, const char* registrationToken,
101+
const char* samplingFeatureUUID, uint8_t sendEveryX = 1,
102+
uint8_t sendOffset = 0);
103+
/**
104+
* @brief Construct a new Hologram Publisher object
105+
*
106+
* @param baseLogger The logger supplying the data to be published
107+
* @param inClient An Arduino client instance to use to print data to.
108+
* Allows the use of any type of client and multiple clients tied to a
109+
* single TinyGSM modem instance
110+
* @param registrationToken The registration token for the site on the
111+
* Monitor My Watershed data portal.
112+
* @param samplingFeatureUUID The sampling feature UUID for the site on the
113+
* Monitor My Watershed data portal.
114+
* @param sendEveryX Currently unimplemented, intended for future use to
115+
* enable caching and bulk publishing
116+
* @param sendOffset Currently unimplemented, intended for future use to
117+
* enable publishing data at a time slightly delayed from when it is
118+
* collected
119+
*/
120+
HologramPublisher(Logger& baseLogger, Client* inClient,
121+
const char* registrationToken,
122+
const char* samplingFeatureUUID, uint8_t sendEveryX = 1,
123+
uint8_t sendOffset = 0);
124+
/**
125+
* @brief Destroy the EnviroDIY Publisher object
126+
*/
51127
virtual ~HologramPublisher();
52128

53129
// Returns the data destination
54-
virtual String getEndpoint(void){return String(hologramHost);}
130+
String getEndpoint(void) override {
131+
return String(hologramHost);
132+
}
55133

56134
// Adds the site registration token
57-
void setToken(const char *registrationToken);
135+
/**
136+
* @brief Set the site registration token
137+
*
138+
* @param registrationToken The registration token for the site on the
139+
* Monitor My Watershed data portal.
140+
*/
141+
void setToken(const char* registrationToken);
58142

59-
// Calculates how long the JSON will be
143+
/**
144+
* @brief Calculates how long the outgoing JSON will be
145+
*
146+
* @return uint16_t The number of characters in the JSON object.
147+
*/
60148
uint16_t calculateJsonSize();
61-
// Calculates how long the full post request will be, including headers
149+
// /**
150+
// * @brief Calculates how long the full post request will be, including
151+
// * headers
152+
// *
153+
// * @return uint16_t The length of the full request including HTTP
154+
// headers.
155+
// */
62156
// uint16_t calculatePostSize();
63157

64-
// This generates a properly formatted JSON for EnviroDIY
65-
void printSensorDataJSON(Stream *stream);
158+
/**
159+
* @brief This generates a properly formatted JSON for EnviroDIY and prints
160+
* it to the input Arduino stream object.
161+
*
162+
* @param stream The Arduino stream to write out the JSON to.
163+
*/
164+
void printSensorDataJSON(Stream* stream);
66165

67-
// This prints a fully structured post request for WikiWatershed/EnviroDIY
68-
// to the specified stream.
69-
void printEnviroDIYRequest(Stream *stream);
166+
/**
167+
* @brief This prints a fully structured post request for Monitor My
168+
* Watershed/EnviroDIY to the specified stream.
169+
*
170+
* @param stream The Arduino stream to write out the request to.
171+
*/
172+
void printEnviroDIYRequest(Stream* stream);
70173

71174
// A way to begin with everything already set
72-
void begin(Logger& baseLogger, Client *inClient,
73-
const char *registrationToken,
74-
const char *samplingFeatureUUID);
75-
void begin(Logger& baseLogger,
76-
const char *registrationToken,
77-
const char *samplingFeatureUUID);
78-
79-
// This utilizes an attached modem to make a TCP connection to the
80-
// EnviroDIY/ODM2DataSharingPortal and then streams out a post request
81-
// over that connection.
82-
// The return is the http status code of the response.
175+
/**
176+
* @copydoc dataPublisher::begin(Logger& baseLogger, Client* inClient)
177+
* @param registrationToken The registration token for the site on the
178+
* Monitor My Watershed data portal.
179+
* @param samplingFeatureUUID The sampling feature UUID for the site on the
180+
* Monitor My Watershed data portal.
181+
*/
182+
void begin(Logger& baseLogger, Client* inClient,
183+
const char* registrationToken, const char* samplingFeatureUUID);
184+
/**
185+
* @copydoc dataPublisher::begin(Logger& baseLogger)
186+
* @param registrationToken The registration token for the site on the
187+
* Monitor My Watershed data portal.
188+
* @param samplingFeatureUUID The sampling feature UUID for the site on the
189+
* Monitor My Watershed data portal.
190+
*/
191+
void begin(Logger& baseLogger, const char* registrationToken,
192+
const char* samplingFeatureUUID);
193+
83194
// int16_t postDataEnviroDIY(void);
84-
virtual int16_t publishData(Client *_outClient);
195+
/**
196+
* @brief Utilize an attached modem to open a a TCP connection to the
197+
* EnviroDIY/ODM2DataSharingPortal and then stream out a post request over
198+
* that connection.
199+
*
200+
* This depends on an internet connection already having been made and a
201+
* client being available.
202+
*
203+
* @param outClient An Arduino client instance to use to print data to.
204+
* Allows the use of any type of client and multiple clients tied to a
205+
* single TinyGSM modem instance
206+
* @return **int16_t** The http status code of the response.
207+
*/
208+
int16_t publishData(Client* outClient) override;
85209

86210
protected:
87211

88-
// portions of the POST request
212+
/**
213+
* @anchor hologram_post_vars
214+
* @name Portions of the POST request to Hologram
215+
*
216+
* @{
217+
*/
89218
static const char* postEndpoint; ///< The endpoint
90219
static const char* hologramHost; ///< The host name
91220
static const int hologramPort; ///< The host port
@@ -94,8 +223,14 @@ class HologramPublisher : public dataPublisher {
94223
// static const char *connectionHeader; ///< The keep alive header text
95224
static const char* contentLengthHeader; ///< The content length header text
96225
static const char* contentTypeHeader; ///< The content type header text
226+
/**@}*/
97227

98-
// portions of the JSON
228+
/**
229+
* @anchor hologram_json_vars
230+
* @name Portions of the JSON object for Hologram
231+
*
232+
* @{
233+
*/
99234
static const char* deviceIdTag; ///< The Hologram device ID tag
100235
static const char* bodyTag; ///< The Hologram body content tag
101236
static const char* deviceId; ///< The Hologram device ID

0 commit comments

Comments
 (0)