diff --git a/src/NoteI2c.hpp b/src/NoteI2c.hpp index a0a9f9e..13e42b6 100644 --- a/src/NoteI2c.hpp +++ b/src/NoteI2c.hpp @@ -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 @@ -25,11 +33,11 @@ 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`. */ /**************************************************************************/ @@ -37,12 +45,17 @@ class NoteI2c /**************************************************************************/ /*! - @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 @@ -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 */ @@ -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. diff --git a/src/NoteI2c_Arduino.cpp b/src/NoteI2c_Arduino.cpp index b7673c2..9d2d8ef 100644 --- a/src/NoteI2c_Arduino.cpp +++ b/src/NoteI2c_Arduino.cpp @@ -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 @@ -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 @@ -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(_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; @@ -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; @@ -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; diff --git a/src/NoteSerial.hpp b/src/NoteSerial.hpp index 3245f68..6338834 100644 --- a/src/NoteSerial.hpp +++ b/src/NoteSerial.hpp @@ -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 @@ -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. diff --git a/test/NoteI2c_Arduino.test.cpp b/test/NoteI2c_Arduino.test.cpp index b69ebc7..6e7e739 100644 --- a/test/NoteI2c_Arduino.test.cpp +++ b/test/NoteI2c_Arduino.test.cpp @@ -756,7 +756,7 @@ int test_notei2c_arduino_receive_returns_error_message_on_i2c_transmission_failu // Arrange const uint16_t EXPECTED_ADDRESS = 0x17; const uint8_t REQUEST_SIZE = 13; - const char * EXPECTED_RESULT = "i2c: data too long to fit in transmit buffer {io}"; + const char * EXPECTED_RESULT = "i2c|rx: data too long to fit in transmit buffer {io}{i2c}"; uint8_t response_buffer[32]; uint32_t bytes_remaining; @@ -804,7 +804,7 @@ int test_notei2c_arduino_receive_returns_error_message_on_i2c_transmission_failu // Arrange const uint16_t EXPECTED_ADDRESS = 0x17; const uint8_t REQUEST_SIZE = 13; - const char * EXPECTED_RESULT = "i2c: received NACK on transmit of address {io}"; + const char * EXPECTED_RESULT = "i2c|rx: received NACK on transmit of address {io}{i2c}"; uint8_t response_buffer[32]; uint32_t bytes_remaining; @@ -852,7 +852,7 @@ int test_notei2c_arduino_receive_returns_error_message_on_i2c_transmission_failu // Arrange const uint16_t EXPECTED_ADDRESS = 0x17; const uint8_t REQUEST_SIZE = 13; - const char * EXPECTED_RESULT = "i2c: received NACK on transmit of data {io}"; + const char * EXPECTED_RESULT = "i2c|rx: received NACK on transmit of data {io}{i2c}"; uint8_t response_buffer[32]; uint32_t bytes_remaining; @@ -900,7 +900,7 @@ int test_notei2c_arduino_receive_returns_error_message_on_i2c_transmission_failu // Arrange const uint16_t EXPECTED_ADDRESS = 0x17; const uint8_t REQUEST_SIZE = 13; - const char * EXPECTED_RESULT = "i2c: unknown error on TwoWire::endTransmission() {io}"; + const char * EXPECTED_RESULT = "i2c|rx: unknown error on TwoWire::endTransmission() {io}{i2c}"; uint8_t response_buffer[32]; uint32_t bytes_remaining; @@ -948,7 +948,7 @@ int test_notei2c_arduino_receive_returns_error_message_on_i2c_transmission_failu // Arrange const uint16_t EXPECTED_ADDRESS = 0x17; const uint8_t REQUEST_SIZE = 13; - const char * EXPECTED_RESULT = "i2c: timeout {io}"; + const char * EXPECTED_RESULT = "i2c|rx: timeout {io}{i2c}"; uint8_t response_buffer[32]; uint32_t bytes_remaining; @@ -996,7 +996,7 @@ int test_notei2c_arduino_receive_returns_error_message_on_unexpected_i2c_transmi // Arrange const uint16_t EXPECTED_ADDRESS = 0x17; const uint8_t REQUEST_SIZE = 13; - const char * EXPECTED_RESULT = "i2c: unknown error encounter during I2C transmission {io}"; + const char * EXPECTED_RESULT = "i2c|rx: unknown error encountered during I2C transmission {io}{i2c}"; uint8_t response_buffer[32]; uint32_t bytes_remaining; @@ -1037,14 +1037,14 @@ int test_notei2c_arduino_receive_returns_error_message_on_unexpected_i2c_transmi return result; } -int test_notei2c_arduino_receive_returns_error_message_on_serial_over_i2c_protocol_failure_to_respond() +int test_notei2c_arduino_receive_returns_error_message_on_i2c_protocol_failure_to_respond() { int result; // Arrange const uint16_t EXPECTED_ADDRESS = 0x17; const uint8_t REQUEST_SIZE = 13; - const char * EXPECTED_RESULT = "serial-over-i2c: no response to read request {io}"; + const char * EXPECTED_RESULT = "i2c|rx: no response to read request {io}{i2c}"; uint8_t response_buffer[32]; uint32_t bytes_remaining; @@ -1083,14 +1083,14 @@ int test_notei2c_arduino_receive_returns_error_message_on_serial_over_i2c_protoc return result; } -int test_notei2c_arduino_receive_returns_error_message_on_serial_over_i2c_protocol_unexpected_raw_byte_count() +int test_notei2c_arduino_receive_returns_error_message_on_i2c_protocol_unexpected_raw_byte_count() { int result; // Arrange const uint16_t EXPECTED_ADDRESS = 0x17; const uint8_t REQUEST_SIZE = 13; - const char * EXPECTED_RESULT = "serial-over-i2c: unexpected raw byte count {io}"; + const char * EXPECTED_RESULT = "i2c|rx: unexpected raw byte count {io}{i2c}"; uint8_t response_buffer[32]; uint32_t bytes_remaining; @@ -1138,7 +1138,7 @@ int test_notei2c_arduino_receive_returns_error_message_on_serial_over_i2c_protoc const uint8_t AVAILABLE_SIZE = ((NoteI2c_Arduino::REQUEST_MAX_SIZE - NoteI2c_Arduino::REQUEST_HEADER_SIZE) + 1); const uint16_t EXPECTED_ADDRESS = 0x17; const uint8_t REQUEST_SIZE = 13; - const char * EXPECTED_RESULT = "serial-over-i2c: available byte count greater than max allowed {io}"; + const char * EXPECTED_RESULT = "serial-over-i2c|rx: available byte count greater than max allowed {io}{i2c}"; uint8_t response_buffer[32]; uint32_t bytes_remaining; @@ -1185,7 +1185,7 @@ int test_notei2c_arduino_receive_returns_error_message_on_serial_over_i2c_protoc // Arrange const uint16_t EXPECTED_ADDRESS = 0x17; const uint8_t REQUEST_SIZE = 13; - const char * EXPECTED_RESULT = "serial-over-i2c: unexpected protocol byte count {io}"; + const char * EXPECTED_RESULT = "serial-over-i2c|rx: unexpected protocol byte count {io}{i2c}"; uint8_t response_buffer[32]; uint32_t bytes_remaining; @@ -1443,7 +1443,7 @@ int test_notei2c_arduino_transmit_returns_error_message_on_i2c_transmission_fail const uint16_t EXPECTED_ADDRESS = 0x17; uint8_t write_buffer[17] = {'H','e','l','l','o',',',' ','N','o','t','e','c','a','r','d','!','\0'}; const uint8_t REQUEST_SIZE = sizeof(write_buffer); - const char * EXPECTED_RESULT = "i2c: data too long to fit in transmit buffer {io}"; + const char * EXPECTED_RESULT = "i2c|tx: data too long to fit in transmit buffer {io}{i2c}"; twoWireBeginTransmission_Parameters.reset(); twoWireWriteByte_Parameters.reset(); @@ -1486,7 +1486,7 @@ int test_notei2c_arduino_transmit_returns_error_message_on_i2c_transmission_fail const uint16_t EXPECTED_ADDRESS = 0x17; uint8_t write_buffer[17] = {'H','e','l','l','o',',',' ','N','o','t','e','c','a','r','d','!','\0'}; const uint8_t REQUEST_SIZE = sizeof(write_buffer); - const char * EXPECTED_RESULT = "i2c: received NACK on transmit of address {io}"; + const char * EXPECTED_RESULT = "i2c|tx: received NACK on transmit of address {io}{i2c}"; twoWireBeginTransmission_Parameters.reset(); twoWireWriteByte_Parameters.reset(); @@ -1529,7 +1529,7 @@ int test_notei2c_arduino_transmit_returns_error_message_on_i2c_transmission_fail const uint16_t EXPECTED_ADDRESS = 0x17; uint8_t write_buffer[17] = {'H','e','l','l','o',',',' ','N','o','t','e','c','a','r','d','!','\0'}; const uint8_t REQUEST_SIZE = sizeof(write_buffer); - const char * EXPECTED_RESULT = "i2c: received NACK on transmit of data {io}"; + const char * EXPECTED_RESULT = "i2c|tx: received NACK on transmit of data {io}{i2c}"; twoWireBeginTransmission_Parameters.reset(); twoWireWriteByte_Parameters.reset(); @@ -1572,7 +1572,7 @@ int test_notei2c_arduino_transmit_returns_error_message_on_i2c_transmission_fail const uint16_t EXPECTED_ADDRESS = 0x17; uint8_t write_buffer[17] = {'H','e','l','l','o',',',' ','N','o','t','e','c','a','r','d','!','\0'}; const uint8_t REQUEST_SIZE = sizeof(write_buffer); - const char * EXPECTED_RESULT = "i2c: unknown error on TwoWire::endTransmission() {io}"; + const char * EXPECTED_RESULT = "i2c|tx: unknown error on TwoWire::endTransmission() {io}{i2c}"; twoWireBeginTransmission_Parameters.reset(); twoWireWriteByte_Parameters.reset(); @@ -1615,7 +1615,7 @@ int test_notei2c_arduino_transmit_returns_error_message_on_i2c_transmission_fail const uint16_t EXPECTED_ADDRESS = 0x17; uint8_t write_buffer[17] = {'H','e','l','l','o',',',' ','N','o','t','e','c','a','r','d','!','\0'}; const uint8_t REQUEST_SIZE = sizeof(write_buffer); - const char * EXPECTED_RESULT = "i2c: timeout {io}"; + const char * EXPECTED_RESULT = "i2c|tx: timeout {io}{i2c}"; twoWireBeginTransmission_Parameters.reset(); twoWireWriteByte_Parameters.reset(); @@ -1658,7 +1658,7 @@ int test_notei2c_arduino_transmit_returns_error_message_on_unexpected_i2c_transm const uint16_t EXPECTED_ADDRESS = 0x17; uint8_t write_buffer[17] = {'H','e','l','l','o',',',' ','N','o','t','e','c','a','r','d','!','\0'}; const uint8_t REQUEST_SIZE = sizeof(write_buffer); - const char * EXPECTED_RESULT = "i2c: unknown error encounter during I2C transmission {io}"; + const char * EXPECTED_RESULT = "i2c|tx: unknown error encountered during I2C transmission {io}{i2c}"; twoWireBeginTransmission_Parameters.reset(); twoWireWriteByte_Parameters.reset(); @@ -1723,8 +1723,8 @@ int main(void) {test_notei2c_arduino_receive_returns_error_message_on_i2c_transmission_failure_4, "test_notei2c_arduino_receive_returns_error_message_on_i2c_transmission_failure_4"}, {test_notei2c_arduino_receive_returns_error_message_on_i2c_transmission_failure_5, "test_notei2c_arduino_receive_returns_error_message_on_i2c_transmission_failure_5"}, {test_notei2c_arduino_receive_returns_error_message_on_unexpected_i2c_transmission_failure, "test_notei2c_arduino_receive_returns_error_message_on_unexpected_i2c_transmission_failure"}, - {test_notei2c_arduino_receive_returns_error_message_on_serial_over_i2c_protocol_failure_to_respond, "test_notei2c_arduino_receive_returns_error_message_on_serial_over_i2c_protocol_failure_to_respond"}, - {test_notei2c_arduino_receive_returns_error_message_on_serial_over_i2c_protocol_unexpected_raw_byte_count, "test_notei2c_arduino_receive_returns_error_message_on_serial_over_i2c_protocol_unexpected_raw_byte_count"}, + {test_notei2c_arduino_receive_returns_error_message_on_i2c_protocol_failure_to_respond, "test_notei2c_arduino_receive_returns_error_message_on_i2c_protocol_failure_to_respond"}, + {test_notei2c_arduino_receive_returns_error_message_on_i2c_protocol_unexpected_raw_byte_count, "test_notei2c_arduino_receive_returns_error_message_on_i2c_protocol_unexpected_raw_byte_count"}, {test_notei2c_arduino_receive_returns_error_message_on_serial_over_i2c_protocol_unexpected_available_byte_count, "test_notei2c_arduino_receive_returns_error_message_on_serial_over_i2c_protocol_unexpected_available_byte_count"}, {test_notei2c_arduino_receive_returns_error_message_on_serial_over_i2c_protocol_unexpected_protocol_byte_count, "test_notei2c_arduino_receive_returns_error_message_on_serial_over_i2c_protocol_unexpected_protocol_byte_count"}, {test_notei2c_arduino_reset_invokes_begin_method_on_constructor_twowire_parameter, "test_notei2c_arduino_reset_invokes_begin_method_on_constructor_twowire_parameter"},