linux-wire: fix lifecycle/error handling, preserve TwoWire config, enforce flush failures, add tests

Author: CameronBrooks11

.codex

@@ -12,16 +12,17 @@ typedef struct
     int fd;
     char device_path[LINUX_WIRE_DEVICE_PATH_MAX];
     uint32_t timeout_us;
+    int log_errors;
 } lw_i2c_bus;
 ```
 
 ### Bus Management
 
 | Function                                                    | Description                                                                                        |
 | ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
-| `int lw_open_bus(lw_i2c_bus *bus, const char *path);`       | Opens `/dev/i2c-X` and populates the handle. Returns `0` on success, `-1` on error (sets `errno`). |
+| `int lw_open_bus(lw_i2c_bus *bus, const char *path);`       | Opens `/dev/i2c-X` and populates the handle. Returns `0` on success, `-1` on error (sets `errno`) and resets the handle to a closed state on failure. |
 | `void lw_close_bus(lw_i2c_bus *bus);`                       | Closes the file descriptor if open. Safe to call multiple times.                                   |
-| `int lw_set_slave(lw_i2c_bus *bus, uint8_t addr);`          | Issues `I2C_SLAVE` ioctl to select the target address.                                             |
+| `int lw_set_slave(lw_i2c_bus *bus, uint8_t addr);`          | Issues `I2C_SLAVE` ioctl to select the target address. Rejects values above `0x7F` with `EINVAL`. |
 | `int lw_set_timeout(lw_i2c_bus *bus, uint32_t timeout_us);` | Stores a timeout hint (currently informational).                                                   |
 
 ### Simple Read/Write
@@ -32,7 +33,7 @@ typedef struct
 | `ssize_t lw_read(lw_i2c_bus *bus, uint8_t *data, size_t len);`                       | Reads up to `len` bytes via `read(2)`.                                                                           |
 | `void lw_set_error_logging(lw_i2c_bus *bus, int enable);`                            | Enable (`enable != 0`) or suppress (`enable == 0`) `perror` logging for that bus handle.                         |
 
-Both functions return the number of bytes processed or `-1` on error (`errno` set).
+Both functions return the number of bytes processed or `-1` on error (`errno` set). Closed handles report `EBADF`; malformed arguments report `EINVAL`.
 
 ### Combined Transactions
 
@@ -41,7 +42,7 @@ Both functions return the number of bytes processed or `-1` on error (`errno` se
 | `ssize_t lw_ioctl_read(lw_i2c_bus *bus, uint16_t addr, const uint8_t *iaddr, size_t iaddr_len, uint8_t *data, size_t len, uint16_t flags);`        | Issues an `I2C_RDWR` ioctl with an optional internal register write followed by a read (repeated-start behavior). |
 | `ssize_t lw_ioctl_write(lw_i2c_bus *bus, uint16_t addr, const uint8_t *iaddr, size_t iaddr_len, const uint8_t *data, size_t len, uint16_t flags);` | Builds a single write message combining an optional internal address and payload.                                 |
 
-The helper validates inputs (non-null buffers, length ≤ 4096, etc.) before calling into the kernel.
+The helpers validate inputs (non-null buffers, length ≤ 4096, etc.) before calling into the kernel. Closed handles report `EBADF`; malformed arguments report `EINVAL`.
 
 ---
 
@@ -53,39 +54,43 @@ The helper validates inputs (non-null buffers, length ≤ 4096, etc.) before cal
 
 | Method                                                                               | Description                                                                                                                                        |
 | ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `void begin(const char *device = "/dev/i2c-1");`                                     | Opens the specified I²C device. Calling `begin()` again reopens the bus.                                                                           |
+| `void begin(const char *device = "/dev/i2c-1");`                                     | Opens the specified I²C device. Calling `begin()` again reopens the bus and re-applies stored timeout/logging preferences.                           |
 | `void begin(uint8_t); void begin(int);`                                              | Provided for Arduino compatibility; they’re no-ops in Linux master mode.                                                                           |
 | `void end();`                                                                        | Closes the bus and clears buffers.                                                                                                                 |
 | `void setClock(uint32_t frequency);`                                                 | Currently a no-op (bus speed is controlled by the kernel).                                                                                         |
-| `void setWireTimeout(uint32_t timeout_us = 25000, bool reset_with_timeout = false);` | Stores a timeout threshold; when the underlying I/O reports `ETIMEDOUT`, `getWireTimeoutFlag()` becomes true and (optionally) the bus is reopened. |
+| `void setWireTimeout(uint32_t timeout_us = 25000, bool reset_with_timeout = false);` | Stores a timeout threshold; when the underlying I/O reports `ETIMEDOUT`, `getWireTimeoutFlag()` becomes true and (optionally) the bus is reopened with the same timeout hint still applied. |
 | `bool getWireTimeoutFlag() const;` / `void clearWireTimeoutFlag();`                  | Query/reset the timeout flag.                                                                                                                      |
-| `void setErrorLogging(bool enable);`                                                 | Toggle low-level `perror` logging (handy when probing addresses that are expected to NACK).                                                        |
+| `void setErrorLogging(bool enable);`                                                 | Toggle low-level `perror` logging (handy when probing addresses that are expected to NACK). The preference survives reopen operations.              |
 
 ### Master Transmit
 
 | Method                                                                                                              | Description                                                                                                                                                                                                           |
 | ------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `void beginTransmission(uint8_t address);`                                                                          | Starts buffering data for the given device.                                                                                                                                                                           |
 | `void beginTransmission(int address);`                                                                              | Overload that forwards to the `uint8_t` version.                                                                                                                                                                      |
-| `uint8_t endTransmission(uint8_t sendStop = 1);`                                                                    | Writes the buffered bytes. Return codes match Arduino: `0` success, `1` buffer overflow, `4` other error. Passing `0` for `sendStop` defers the actual write until the next `requestFrom` (repeated-start semantics). |
+| `uint8_t endTransmission(uint8_t sendStop = 1);`                                                                    | Writes the buffered bytes. Return codes match Arduino: `0` success, `1` buffer overflow, `4` other error. Passing `0` for `sendStop` defers the actual write until the next `requestFrom` (repeated-start semantics). If an older deferred write must be auto-flushed first and that flush fails, this call returns `4`. |
 | `size_t write(uint8_t data);` / `size_t write(const uint8_t *data, size_t len);` / `size_t write(const char *str);` | Append data to the TX buffer (up to 32 bytes).                                                                                                                                                                        |
 
 ### Master Receive
 
 | Method                                                                                                              | Description                                                                                                                                        |
 | ------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `uint8_t requestFrom(uint8_t address, uint8_t quantity, uint8_t sendStop = 1);`                                     | Reads up to `quantity` bytes. If prior `endTransmission(false)` buffered data for the same address, it performs a combined `I2C_RDWR` transaction. |
+| `uint8_t requestFrom(uint8_t address, uint8_t quantity, uint8_t sendStop = 1);`                                     | Reads up to `quantity` bytes. If prior `endTransmission(false)` buffered data for the same address, it performs a combined `I2C_RDWR` transaction. If a deferred write must be auto-flushed first and that flush fails, the read is aborted and `0` is returned. |
 | `uint8_t requestFrom(uint8_t address, uint8_t quantity, uint32_t iaddress, uint8_t isize, uint8_t sendStop);`       | Arduino-style register helper; `isize` is clamped to 4.                                                                                            |
 | `uint8_t requestFrom(int address, int quantity);` / `uint8_t requestFrom(int address, int quantity, int sendStop);` | Compatibility overloads.                                                                                                                           |
 | `int available() const; int read(); int peek(); void flush();`                                                      | Buffer inspection helpers matching Arduino semantics.                                                                                              |
 
 ### Repeated-start semantics
 
-- `endTransmission(false)` leaves the TX buffer intact for the next `requestFrom` to the same address. If you later target a different address or call `beginTransmission` without a read in between, linux-wire automatically flushes the pending data with a STOP so nothing is silently dropped.
+- `endTransmission(false)` leaves the TX buffer intact for the next `requestFrom` to the same address.
+- If you later target a different address or call `beginTransmission` without a read in between, linux-wire automatically flushes the pending data with a STOP.
+- If that automatic flush fails, the follow-on operation fails instead of silently proceeding.
 
 ### Timeout behavior
 
-- When `lw_read`/`lw_ioctl_read` reports `ETIMEDOUT`, `wireTimeoutFlag_` is set. If `reset_with_timeout` was true when `setWireTimeout` was called, the bus descriptor is closed and reopened automatically.
+- When `lw_read`/`lw_ioctl_read` reports `ETIMEDOUT`, `wireTimeoutFlag_` is set.
+- If `reset_with_timeout` was true when `setWireTimeout` was called, the bus descriptor is closed and reopened automatically.
+- Stored timeout and error-logging preferences are re-applied after that reopen.
 
 ---
 
@@ -97,4 +102,4 @@ See the `examples/` directory for concrete flows:
 - `master_writer`: simple register write.
 - `master_reader`: demonstrates `endTransmission(false)` + `requestFrom` repeated-start read.
 
-For mock-based tests of buffer management and timeout logic, inspect `tests/test_wire.cpp`.
+For mock-based tests of buffer management, deferred-write failure handling, and timeout logic, inspect `tests/test_wire.cpp`.

docs/api.md

@@ -90,12 +90,12 @@ int main() {
 Important Arduino-parity notes:
 
 - `requestFrom(address, quantity, iaddress, isize, sendStop)` exists and clamps `isize` to 4 bytes, mirroring the upstream Wire overload.
-- Calling `endTransmission(false)` leaves the TX buffer intact for the next `requestFrom` to the same address. If no read follows, the buffer is flushed with a STOP before the next transmission to avoid silently dropping data.
-- `setWireTimeout(timeout_us, reset_on_timeout)` sets a flag when Linux reports `ETIMEDOUT`. If `reset_on_timeout` is true, the bus handle is closed and reopened automatically (matching the AVR `twi` reset behavior).
+- Calling `endTransmission(false)` leaves the TX buffer intact for the next `requestFrom` to the same address. If no read follows, the buffer is flushed with a STOP before the next operation; if that automatic flush fails, the follow-on operation fails instead of silently continuing.
+- `setWireTimeout(timeout_us, reset_on_timeout)` sets a flag when Linux reports `ETIMEDOUT`. If `reset_on_timeout` is true, the bus handle is closed and reopened automatically (matching the AVR `twi` reset behavior), and stored timeout/logging preferences are re-applied.
 
 ## Testing
 
-Software-only tests live in `tests/`. They use a mock `lw_*` backend to exercise buffer management, repeated-start logic, and timeout handling without real hardware:
+Software-only tests live in `tests/`. They use a mock `lw_*` backend to exercise buffer management, repeated-start logic, deferred-write failure handling, and timeout handling without real hardware:
 
 ```sh
 ctest --test-dir build --output-on-failure

docs/index.md

@@ -64,6 +64,8 @@ class TwoWire
      *   Wire.begin("/dev/i2c-0");  // Uses /dev/i2c-0
      *
      * Note: If already open, this will close and reopen the bus.
+     *       Stored timeout and error-logging preferences are re-applied
+     *       after every successful open.
      */
     void begin(const char *device = "/dev/i2c-1");
 
@@ -106,6 +108,8 @@ class TwoWire
      *
      * Note: Timeout enforcement is currently informational only.
      *       Future versions may implement actual timeout via select/poll.
+     *       The configured timeout hint is preserved across `begin()` and
+     *       timeout-triggered reopen operations.
      */
     void setWireTimeout(uint32_t timeout_us = 25000, bool reset_with_timeout = false);
 
@@ -124,6 +128,9 @@ class TwoWire
     /**
      * Enable or disable error messages printed by the low-level I2C helpers.
      * Useful when deliberately probing addresses that will NACK (e.g., strict scanner).
+     *
+     * The chosen setting is preserved across `begin()` and timeout-triggered
+     * reopen operations.
      */
     void setErrorLogging(bool enable);
 
@@ -159,6 +166,9 @@ class TwoWire
      *       requestFrom() call, avoiding an intervening STOP condition.
      *       The actual STOP is still issued by the kernel driver; this
      *       just controls whether to use combined ioctl transactions.
+     *       If an older deferred write must be auto-flushed first and that
+     *       flush fails, this method returns 4 and does not send the new
+     *       transmission.
      */
     uint8_t endTransmission(uint8_t sendStop);
     uint8_t endTransmission(void);
@@ -177,6 +187,10 @@ class TwoWire
      * After successful call, use available(), read(), and peek() to
      * access the received data.
      *
+     * If a deferred write from `endTransmission(false)` must be auto-flushed
+     * before starting this read and that flush fails, this method returns 0
+     * and does not start the read.
+     *
      * Examples:
      *   // Simple read
      *   Wire.requestFrom(0x40, 2);
@@ -245,6 +259,7 @@ class TwoWire
 private:
     lw_i2c_bus bus_;
     bool bus_open_;
+    bool errorLoggingEnabled_;
 
     char devicePath_[LINUX_WIRE_DEVICE_PATH_MAX];
     uint8_t txAddress_;
@@ -266,6 +281,7 @@ class TwoWire
 
     void resetTxBuffer();
     void resetRxBuffer();
+    void applyBusConfiguration();
 
     uint8_t requestFrom(uint8_t address,
                         uint8_t quantity,

include/Wire.h

@@ -27,6 +27,7 @@ extern "C"
      *   device_path - Path used to open the bus (e.g., "/dev/i2c-1")
      *   timeout_us  - Timeout value in microseconds (0 = no timeout)
      *                 Currently informational only; not enforced by implementation
+     *   log_errors  - Non-zero enables perror logging for low-level failures
      */
     typedef struct
     {
@@ -51,7 +52,7 @@ extern "C"
      *   EACCES - Permission denied (user may need to be in 'i2c' group)
      *
      * On success, bus->fd contains a valid file descriptor.
-     * On failure, bus->fd is set to -1.
+     * On failure, the bus handle is reset to a closed state (`fd == -1`).
      *
      * Example:
      *   lw_i2c_bus bus;
@@ -100,9 +101,9 @@ extern "C"
      * @return Number of bytes written on success, -1 on error (errno set)
      *
      * Error conditions:
-     *   EINVAL   - Invalid parameters
-     *   EBADF    - Bus not open
-     *   ENXIO    - No device at selected address (NACK)
+     *   EINVAL    - Invalid parameters (NULL pointers, NULL buffer with len > 0)
+     *   EBADF     - Bus not open
+     *   ENXIO     - No device at selected address (NACK)
      *   ETIMEDOUT - Communication timeout
      *
      * Note: The send_stop parameter is accepted for API compatibility but
@@ -125,7 +126,7 @@ extern "C"
      * @return Number of bytes read on success, -1 on error (errno set)
      *
      * Error conditions:
-     *   EINVAL   - Invalid parameters
+     *   EINVAL   - Invalid parameters (NULL pointers, NULL buffer with len > 0)
      *   EBADF    - Bus not open
      *   ENXIO    - No device at selected address (NACK)
      *   ETIMEDOUT - Communication timeout
@@ -232,6 +233,9 @@ extern "C"
      *
      * @param bus Pointer to lw_i2c_bus
      * @param enable Non-zero to enable logging, zero to suppress
+     *
+     * This preference is also re-applied by the C++ wrapper after automatic
+     * timeout recovery and fresh `begin()` calls.
      */
     void lw_set_error_logging(lw_i2c_bus *bus, int enable);