Skip to content

Commit d139b22

Browse files
zfieldsCopilot
zfields
and
Copilot
authored
chore: Update API documentation (#151)
* chore: Update API documentation chore: improve i2c error messages fix: typo caught in code review Co-authored-by: Copilot <[email protected]>
1 parent e8e1cda commit d139b22

File tree

4 files changed

+84
-64
lines changed

4 files changed

+84
-64
lines changed

‎src/NoteI2c.hpp‎

Lines changed: 25 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -12,11 +12,19 @@ class NoteI2c
1212

1313
/**************************************************************************/
1414
/*!
15-
@brief Receives an amount of data from the Notecard in blocking mode.
15+
@brief The Serial-over-I2C protocol receive callback implementation
16+
17+
A blocking transaction filling the provided buffer with the requested
18+
number of bytes from the Notecard at the provided address. Upon success,
19+
a `nullptr` is returned, and `available` will populated with the number
20+
of bytes the Notecard is waiting to send. Otherwise, an error string
21+
describing the failure will be returned.
22+
1623
@param[in] device_address
1724
The I2C address.
1825
@param[out] buffer
19-
A buffer to hold the data read from the I2C controller.
26+
A buffer to hold the data read from the I2C controller. The
27+
buffer must be at least `requested_byte_count` bytes long.
2028
@param[in] requested_byte_count
2129
The number of bytes requested.
2230
@param[out] available
@@ -25,24 +33,29 @@ class NoteI2c
2533
successful.
2634
*/
2735
/**************************************************************************/
28-
virtual const char * receive(uint16_t device_address, uint8_t * buffer, uint16_t size, uint32_t * available) = 0;
36+
virtual const char * receive(uint16_t device_address, uint8_t * buffer, uint16_t requested_byte_count, uint32_t * available) = 0;
2937

3038
/**************************************************************************/
3139
/*!
32-
@brief Resets the I2C port. Required by note-c.
40+
@brief The Serial-over-I2C protocol reset callback implementation
3341
@return `true`.
3442
*/
3543
/**************************************************************************/
3644
virtual bool reset(uint16_t device_address) = 0;
3745

3846
/**************************************************************************/
3947
/*!
40-
@brief Transmits an amount of data from the host in blocking mode.
48+
@brief The Serial-over-I2C protocol transmit callback implementation
49+
50+
A blocking transaction sending the provided buffer to the Notecard at
51+
the provided address. Upon success, a `nullptr` is returned, otherwise
52+
an error string describing the failure will be returned.
53+
4154
@param[in] device_address
4255
The I2C address.
4356
@param[in] buffer
44-
The data to transmit over I2C. The caller should have shifted
45-
it right so that the low bit is NOT the read/write bit.
57+
The data to transmit over I2C. The caller should have already
58+
shifted it right so that the low bit is NOT the read/write bit.
4659
@param[in] size
4760
The number of bytes to transmit.
4861
@returns A string with an error, or `nullptr` if the transmission was
@@ -56,8 +69,7 @@ class NoteI2c
5669
@brief Size of the header for Serial-Over-I2C requests.
5770
5871
@details The request made to the low-level I2C controller should be
59-
for REQUEST_HEADER_SIZE + the `size` parameter supplied to the
60-
`receive` method.
72+
for the `size` parameter supplied to the `receive` method.
6173
6274
@see NoteI2c::receive
6375
*/
@@ -80,9 +92,12 @@ class NoteI2c
8092

8193
/******************************************************************************/
8294
/*!
83-
@brief Helper function to abstract, create and maintain a single instance
95+
@brief Creates a NoteI2c instance
96+
97+
Helper function to abstract, create and maintain a single instance
8498
of the NoteI2c interface implementation, as required by the underlying
8599
`note-c` library.
100+
86101
@param[in] i2c_parameters
87102
Pointer to the parameters required to instantiate
88103
the platform specific I2C implementation.

‎src/NoteI2c_Arduino.cpp‎

Lines changed: 34 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
#include "Notecard.h"
44

55
#if defined(NOTE_C_LOW_MEM)
6-
static const char *i2cerr = "i2c {io}";
6+
static const char *i2cerr = "{io}{i2c}";
77
#endif
88

99
// Singleton instance of the NoteI2c_Arduino class
@@ -85,22 +85,22 @@ NoteI2c_Arduino::receive (
8585
result = nullptr;
8686
break;
8787
case 1:
88-
result = ERRSTR("i2c: data too long to fit in transmit buffer {io}",i2cerr);
88+
result = ERRSTR("i2c|rx: data too long to fit in transmit buffer {io}{i2c}",i2cerr);
8989
break;
9090
case 2:
91-
result = ERRSTR("i2c: received NACK on transmit of address {io}",i2cerr);
91+
result = ERRSTR("i2c|rx: received NACK on transmit of address {io}{i2c}",i2cerr);
9292
break;
9393
case 3:
94-
result = ERRSTR("i2c: received NACK on transmit of data {io}",i2cerr);
94+
result = ERRSTR("i2c|rx: received NACK on transmit of data {io}{i2c}",i2cerr);
9595
break;
9696
case 4:
97-
result = ERRSTR("i2c: unknown error on TwoWire::endTransmission() {io}",i2cerr);
97+
result = ERRSTR("i2c|rx: unknown error on TwoWire::endTransmission() {io}{i2c}",i2cerr);
9898
break;
9999
case 5:
100-
result = ERRSTR("i2c: timeout {io}",i2cerr);
100+
result = ERRSTR("i2c|rx: timeout {io}{i2c}",i2cerr);
101101
break;
102102
default:
103-
result = ERRSTR("i2c: unknown error encounter during I2C transmission {io}",i2cerr);
103+
result = ERRSTR("i2c|rx: unknown error encountered during I2C transmission {io}{i2c}",i2cerr);
104104
}
105105

106106
// Read and cache response from Notecard
@@ -112,18 +112,18 @@ NoteI2c_Arduino::receive (
112112
const int request_length = requested_byte_count_ + NoteI2c::REQUEST_HEADER_SIZE;
113113
const int response_length = _i2cPort.requestFrom((int)device_address_, request_length);
114114
if (!response_length) {
115-
result = ERRSTR("serial-over-i2c: no response to read request {io}",i2cerr);
115+
result = ERRSTR("i2c|rx: no response to read request {io}{i2c}",i2cerr);
116116
} else if (response_length != request_length) {
117-
result = ERRSTR("serial-over-i2c: unexpected raw byte count {io}",i2cerr);
117+
result = ERRSTR("i2c|rx: unexpected raw byte count {io}{i2c}",i2cerr);
118118
} else {
119119
// Ensure available byte count is within expected range
120120
static const size_t AVAILABLE_MAX = (NoteI2c::REQUEST_MAX_SIZE - NoteI2c::REQUEST_HEADER_SIZE);
121121
uint32_t available = _i2cPort.read();
122122
if (available > AVAILABLE_MAX) {
123-
result = ERRSTR("serial-over-i2c: available byte count greater than max allowed {io}",i2cerr);
123+
result = ERRSTR("serial-over-i2c|rx: available byte count greater than max allowed {io}{i2c}",i2cerr);
124124
} else if (requested_byte_count_ != static_cast<uint8_t>(_i2cPort.read())) {
125125
// Ensure protocol response length matches size request
126-
result = ERRSTR("serial-over-i2c: unexpected protocol byte count {io}",i2cerr);
126+
result = ERRSTR("serial-over-i2c|rx: unexpected protocol byte count {io}{i2c}",i2cerr);
127127
} else {
128128
// Update available with remaining bytes
129129
*available_ = available;
@@ -143,7 +143,7 @@ NoteI2c_Arduino::receive (
143143
// the resource contention.
144144
NoteDelayMs(1000);
145145
NOTE_C_LOG_ERROR(result);
146-
NOTE_C_LOG_WARN("serial-over-i2c: reattempting to read Notecard response");
146+
NOTE_C_LOG_WARN("i2c: reattempting to read Notecard response");
147147
} while (result && (i++ < retry_count));
148148

149149
return result;
@@ -177,26 +177,28 @@ NoteI2c_Arduino::transmit (
177177
_i2cPort.write(buffer_, size_);
178178
transmission_error = _i2cPort.endTransmission();
179179

180-
if (transmission_error) {
181-
switch (transmission_error) {
182-
case 1:
183-
result = ERRSTR("i2c: data too long to fit in transmit buffer {io}",i2cerr);
184-
break;
185-
case 2:
186-
result = ERRSTR("i2c: received NACK on transmit of address {io}",i2cerr);
187-
break;
188-
case 3:
189-
result = ERRSTR("i2c: received NACK on transmit of data {io}",i2cerr);
190-
break;
191-
case 4:
192-
result = ERRSTR("i2c: unknown error on TwoWire::endTransmission() {io}",i2cerr);
193-
break;
194-
case 5:
195-
result = ERRSTR("i2c: timeout {io}",i2cerr);
196-
break;
197-
default:
198-
result = ERRSTR("i2c: unknown error encounter during I2C transmission {io}",i2cerr);
199-
}
180+
switch (transmission_error) {
181+
case 0:
182+
// I2C transmission was successful
183+
result = nullptr;
184+
break;
185+
case 1:
186+
result = ERRSTR("i2c|tx: data too long to fit in transmit buffer {io}{i2c}",i2cerr);
187+
break;
188+
case 2:
189+
result = ERRSTR("i2c|tx: received NACK on transmit of address {io}{i2c}",i2cerr);
190+
break;
191+
case 3:
192+
result = ERRSTR("i2c|tx: received NACK on transmit of data {io}{i2c}",i2cerr);
193+
break;
194+
case 4:
195+
result = ERRSTR("i2c|tx: unknown error on TwoWire::endTransmission() {io}{i2c}",i2cerr);
196+
break;
197+
case 5:
198+
result = ERRSTR("i2c|tx: timeout {io}{i2c}",i2cerr);
199+
break;
200+
default:
201+
result = ERRSTR("i2c|tx: unknown error encountered during I2C transmission {io}{i2c}",i2cerr);
200202
}
201203

202204
return result;

‎src/NoteSerial.hpp‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,7 @@ class NoteSerial
3636

3737
/**************************************************************************/
3838
/*!
39-
@brief Writes a message to the Notecard Serial port.
39+
@brief Writes a buffer to the Notecard Serial port.
4040
@param buffer
4141
The bytes to write.
4242
@param size
@@ -51,9 +51,12 @@ class NoteSerial
5151

5252
/******************************************************************************/
5353
/*!
54-
@brief Helper function to abstract, create and maintain a single instance
54+
@brief Creates a NoteSerial instance
55+
56+
Helper function to abstract, create and maintain a single instance
5557
of the NoteSerial interface implementation, as required by the underlying
5658
`note-c` library.
59+
5760
@param[in] serial_parameters
5861
Pointer to the parameters required to instantiate
5962
the platform specific UART implementation.

0 commit comments

Comments
 (0)