Skip to content

Commit 2cd8061

Browse files
zfieldszfields
committed
chore: Update API documentation
chore: improve i2c error messages
1 parent 6a362dc commit 2cd8061

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
@@ -1,7 +1,7 @@
11
#include "NoteI2c_Arduino.hpp"
22

33
#if defined(NOTE_C_LOW_MEM)
4-
static const char *i2cerr = "i2c {io}";
4+
static const char *i2cerr = "{io}{i2c}";
55
#endif
66

77
// Singleton instance of the NoteI2c_Arduino class
@@ -83,22 +83,22 @@ NoteI2c_Arduino::receive (
8383
result = nullptr;
8484
break;
8585
case 1:
86-
result = ERRSTR("i2c: data too long to fit in transmit buffer {io}",i2cerr);
86+
result = ERRSTR("i2c|rx: data too long to fit in transmit buffer {io}{i2c}",i2cerr);
8787
break;
8888
case 2:
89-
result = ERRSTR("i2c: received NACK on transmit of address {io}",i2cerr);
89+
result = ERRSTR("i2c|rx: received NACK on transmit of address {io}{i2c}",i2cerr);
9090
break;
9191
case 3:
92-
result = ERRSTR("i2c: received NACK on transmit of data {io}",i2cerr);
92+
result = ERRSTR("i2c|rx: received NACK on transmit of data {io}{i2c}",i2cerr);
9393
break;
9494
case 4:
95-
result = ERRSTR("i2c: unknown error on TwoWire::endTransmission() {io}",i2cerr);
95+
result = ERRSTR("i2c|rx: unknown error on TwoWire::endTransmission() {io}{i2c}",i2cerr);
9696
break;
9797
case 5:
98-
result = ERRSTR("i2c: timeout {io}",i2cerr);
98+
result = ERRSTR("i2c|rx: timeout {io}{i2c}",i2cerr);
9999
break;
100100
default:
101-
result = ERRSTR("i2c: unknown error encounter during I2C transmission {io}",i2cerr);
101+
result = ERRSTR("i2c|rx: unknown error encounter during I2C transmission {io}{i2c}",i2cerr);
102102
}
103103

104104
// Read and cache response from Notecard
@@ -110,18 +110,18 @@ NoteI2c_Arduino::receive (
110110
const int request_length = requested_byte_count_ + NoteI2c::REQUEST_HEADER_SIZE;
111111
const int response_length = _i2cPort.requestFrom((int)device_address_, request_length);
112112
if (!response_length) {
113-
result = ERRSTR("serial-over-i2c: no response to read request {io}",i2cerr);
113+
result = ERRSTR("i2c|rx: no response to read request {io}{i2c}",i2cerr);
114114
} else if (response_length != request_length) {
115-
result = ERRSTR("serial-over-i2c: unexpected raw byte count {io}",i2cerr);
115+
result = ERRSTR("i2c|rx: unexpected raw byte count {io}{i2c}",i2cerr);
116116
} else {
117117
// Ensure available byte count is within expected range
118118
static const size_t AVAILABLE_MAX = (NoteI2c::REQUEST_MAX_SIZE - NoteI2c::REQUEST_HEADER_SIZE);
119119
uint32_t available = _i2cPort.read();
120120
if (available > AVAILABLE_MAX) {
121-
result = ERRSTR("serial-over-i2c: available byte count greater than max allowed {io}",i2cerr);
121+
result = ERRSTR("serial-over-i2c|rx: available byte count greater than max allowed {io}{i2c}",i2cerr);
122122
} else if (requested_byte_count_ != static_cast<uint8_t>(_i2cPort.read())) {
123123
// Ensure protocol response length matches size request
124-
result = ERRSTR("serial-over-i2c: unexpected protocol byte count {io}",i2cerr);
124+
result = ERRSTR("serial-over-i2c|rx: unexpected protocol byte count {io}{i2c}",i2cerr);
125125
} else {
126126
// Update available with remaining bytes
127127
*available_ = available;
@@ -141,7 +141,7 @@ NoteI2c_Arduino::receive (
141141
// the resource contention.
142142
::delay(1000);
143143
NOTE_C_LOG_ERROR(result);
144-
NOTE_C_LOG_WARN("serial-over-i2c: reattempting to read Notecard response");
144+
NOTE_C_LOG_WARN("i2c: reattempting to read Notecard response");
145145
} while (result && (i++ < retry_count));
146146

147147
return result;
@@ -175,26 +175,28 @@ NoteI2c_Arduino::transmit (
175175
_i2cPort.write(buffer_, size_);
176176
transmission_error = _i2cPort.endTransmission();
177177

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

200202
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)