Skip to content

chore: Update API documentation #151

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Oct 17, 2025
Merged

chore: Update API documentation #151

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
2cd8061
chore: Update API documentation
zfields Oct 16, 2025
499e18e
fix: typo caught in code review
zfields Oct 16, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 25 additions & 10 deletions src/NoteI2c.hpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,11 +12,19 @@ class NoteI2c

/**************************************************************************/
/*!
@brief Receives an amount of data from the Notecard in blocking mode.
@brief The Serial-over-I2C protocol receive callback implementation

A blocking transaction filling the provided buffer with the requested
number of bytes from the Notecard at the provided address. Upon success,
a `nullptr` is returned, and `available` will populated with the number
of bytes the Notecard is waiting to send. Otherwise, an error string
describing the failure will be returned.

@param[in] device_address
The I2C address.
@param[out] buffer
A buffer to hold the data read from the I2C controller.
A buffer to hold the data read from the I2C controller. The
buffer must be at least `requested_byte_count` bytes long.
@param[in] requested_byte_count
The number of bytes requested.
@param[out] available
Expand All @@ -25,24 +33,29 @@ class NoteI2c
successful.
*/
/**************************************************************************/
virtual const char * receive(uint16_t device_address, uint8_t * buffer, uint16_t size, uint32_t * available) = 0;
virtual const char * receive(uint16_t device_address, uint8_t * buffer, uint16_t requested_byte_count, uint32_t * available) = 0;

/**************************************************************************/
/*!
@brief Resets the I2C port. Required by note-c.
@brief The Serial-over-I2C protocol reset callback implementation
@return `true`.
*/
/**************************************************************************/
virtual bool reset(uint16_t device_address) = 0;

/**************************************************************************/
/*!
@brief Transmits an amount of data from the host in blocking mode.
@brief The Serial-over-I2C protocol transmit callback implementation

A blocking transaction sending the provided buffer to the Notecard at
the provided address. Upon success, a `nullptr` is returned, otherwise
an error string describing the failure will be returned.

@param[in] device_address
The I2C address.
@param[in] buffer
The data to transmit over I2C. The caller should have shifted
it right so that the low bit is NOT the read/write bit.
The data to transmit over I2C. The caller should have already
shifted it right so that the low bit is NOT the read/write bit.
@param[in] size
The number of bytes to transmit.
@returns A string with an error, or `nullptr` if the transmission was
Expand All @@ -56,8 +69,7 @@ class NoteI2c
@brief Size of the header for Serial-Over-I2C requests.

@details The request made to the low-level I2C controller should be
for REQUEST_HEADER_SIZE + the `size` parameter supplied to the
`receive` method.
for the `size` parameter supplied to the `receive` method.

@see NoteI2c::receive
*/
Expand All @@ -80,9 +92,12 @@ class NoteI2c

/******************************************************************************/
/*!
@brief Helper function to abstract, create and maintain a single instance
@brief Creates a NoteI2c instance

Helper function to abstract, create and maintain a single instance
of the NoteI2c interface implementation, as required by the underlying
`note-c` library.

@param[in] i2c_parameters
Pointer to the parameters required to instantiate
the platform specific I2C implementation.
Expand Down
66 changes: 34 additions & 32 deletions src/NoteI2c_Arduino.cpp
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
#include "NoteI2c_Arduino.hpp"

#if defined(NOTE_C_LOW_MEM)
static const char *i2cerr = "i2c {io}";
static const char *i2cerr = "{io}{i2c}";
#endif

// Singleton instance of the NoteI2c_Arduino class
Expand Down Expand Up @@ -83,22 +83,22 @@ NoteI2c_Arduino::receive (
result = nullptr;
break;
case 1:
result = ERRSTR("i2c: data too long to fit in transmit buffer {io}",i2cerr);
result = ERRSTR("i2c|rx: data too long to fit in transmit buffer {io}{i2c}",i2cerr);
break;
case 2:
result = ERRSTR("i2c: received NACK on transmit of address {io}",i2cerr);
result = ERRSTR("i2c|rx: received NACK on transmit of address {io}{i2c}",i2cerr);
break;
case 3:
result = ERRSTR("i2c: received NACK on transmit of data {io}",i2cerr);
result = ERRSTR("i2c|rx: received NACK on transmit of data {io}{i2c}",i2cerr);
break;
case 4:
result = ERRSTR("i2c: unknown error on TwoWire::endTransmission() {io}",i2cerr);
result = ERRSTR("i2c|rx: unknown error on TwoWire::endTransmission() {io}{i2c}",i2cerr);
break;
case 5:
result = ERRSTR("i2c: timeout {io}",i2cerr);
result = ERRSTR("i2c|rx: timeout {io}{i2c}",i2cerr);
break;
default:
result = ERRSTR("i2c: unknown error encounter during I2C transmission {io}",i2cerr);
result = ERRSTR("i2c|rx: unknown error encountered during I2C transmission {io}{i2c}",i2cerr);
}

// Read and cache response from Notecard
Expand All @@ -110,18 +110,18 @@ NoteI2c_Arduino::receive (
const int request_length = requested_byte_count_ + NoteI2c::REQUEST_HEADER_SIZE;
const int response_length = _i2cPort.requestFrom((int)device_address_, request_length);
if (!response_length) {
result = ERRSTR("serial-over-i2c: no response to read request {io}",i2cerr);
result = ERRSTR("i2c|rx: no response to read request {io}{i2c}",i2cerr);
} else if (response_length != request_length) {
result = ERRSTR("serial-over-i2c: unexpected raw byte count {io}",i2cerr);
result = ERRSTR("i2c|rx: unexpected raw byte count {io}{i2c}",i2cerr);
} else {
// Ensure available byte count is within expected range
static const size_t AVAILABLE_MAX = (NoteI2c::REQUEST_MAX_SIZE - NoteI2c::REQUEST_HEADER_SIZE);
uint32_t available = _i2cPort.read();
if (available > AVAILABLE_MAX) {
result = ERRSTR("serial-over-i2c: available byte count greater than max allowed {io}",i2cerr);
result = ERRSTR("serial-over-i2c|rx: available byte count greater than max allowed {io}{i2c}",i2cerr);
} else if (requested_byte_count_ != static_cast<uint8_t>(_i2cPort.read())) {
// Ensure protocol response length matches size request
result = ERRSTR("serial-over-i2c: unexpected protocol byte count {io}",i2cerr);
result = ERRSTR("serial-over-i2c|rx: unexpected protocol byte count {io}{i2c}",i2cerr);
} else {
// Update available with remaining bytes
*available_ = available;
Expand All @@ -141,7 +141,7 @@ NoteI2c_Arduino::receive (
// the resource contention.
::delay(1000);
NOTE_C_LOG_ERROR(result);
NOTE_C_LOG_WARN("serial-over-i2c: reattempting to read Notecard response");
NOTE_C_LOG_WARN("i2c: reattempting to read Notecard response");
} while (result && (i++ < retry_count));

return result;
Expand Down Expand Up @@ -175,26 +175,28 @@ NoteI2c_Arduino::transmit (
_i2cPort.write(buffer_, size_);
transmission_error = _i2cPort.endTransmission();

if (transmission_error) {
switch (transmission_error) {
case 1:
result = ERRSTR("i2c: data too long to fit in transmit buffer {io}",i2cerr);
break;
case 2:
result = ERRSTR("i2c: received NACK on transmit of address {io}",i2cerr);
break;
case 3:
result = ERRSTR("i2c: received NACK on transmit of data {io}",i2cerr);
break;
case 4:
result = ERRSTR("i2c: unknown error on TwoWire::endTransmission() {io}",i2cerr);
break;
case 5:
result = ERRSTR("i2c: timeout {io}",i2cerr);
break;
default:
result = ERRSTR("i2c: unknown error encounter during I2C transmission {io}",i2cerr);
}
switch (transmission_error) {
case 0:
// I2C transmission was successful
result = nullptr;
break;
case 1:
result = ERRSTR("i2c|tx: data too long to fit in transmit buffer {io}{i2c}",i2cerr);
break;
case 2:
result = ERRSTR("i2c|tx: received NACK on transmit of address {io}{i2c}",i2cerr);
break;
case 3:
result = ERRSTR("i2c|tx: received NACK on transmit of data {io}{i2c}",i2cerr);
break;
case 4:
result = ERRSTR("i2c|tx: unknown error on TwoWire::endTransmission() {io}{i2c}",i2cerr);
break;
case 5:
result = ERRSTR("i2c|tx: timeout {io}{i2c}",i2cerr);
break;
default:
result = ERRSTR("i2c|tx: unknown error encountered during I2C transmission {io}{i2c}",i2cerr);
}

return result;
Expand Down
7 changes: 5 additions & 2 deletions src/NoteSerial.hpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ class NoteSerial

/**************************************************************************/
/*!
@brief Writes a message to the Notecard Serial port.
@brief Writes a buffer to the Notecard Serial port.
@param buffer
The bytes to write.
@param size
Expand All @@ -51,9 +51,12 @@ class NoteSerial

/******************************************************************************/
/*!
@brief Helper function to abstract, create and maintain a single instance
@brief Creates a NoteSerial instance

Helper function to abstract, create and maintain a single instance
of the NoteSerial interface implementation, as required by the underlying
`note-c` library.

@param[in] serial_parameters
Pointer to the parameters required to instantiate
the platform specific UART implementation.
Expand Down
Loading
Loading