Merge pull request #1 from BloomyControls/eeprom

2.0.0: use I2C EEPROM and add a pulse counter

Author: sophec

CMakeLists.txt

@@ -7,17 +7,37 @@ set(PICO_SDK_FETCH_FROM_GIT_TAG 2.1.1)
 
 include(pico_sdk_import.cmake)
 
-project("pico-ident" VERSION "1.3.0")
+project("pico-ident" VERSION "2.0.0")
 
 pico_sdk_init()
 
-add_executable(pico-ident src/main.c)
+add_executable(pico-ident
+  src/AT24CM02.cpp
+  src/main.cpp
+)
 
 target_link_libraries("${PROJECT_NAME}"
   pico_stdlib
   pico_unique_id
   hardware_flash
-  hardware_gpio)
+  hardware_gpio
+  hardware_i2c
+)
+
+target_compile_features("${PROJECT_NAME}" PUBLIC cxx_std_20)
+
+if (DEFINED MIN_PULSE_WIDTH_US)
+  if (MIN_PULSE_WIDTH_US GREATER_EQUAL 50000)
+    target_compile_definitions("${PROJECT_NAME}" PRIVATE
+      "-DCONFIG_MIN_PULSE_WIDTH_US=${MIN_PULSE_WIDTH_US}"
+    )
+  else()
+    message(FATAL_ERROR
+      "Invalid minimum pulse width: ${MIN_PULSE_WIDTH_US}\n"
+      "MIN_PULSE_WIDTH_US must be a number >= 50000."
+    )
+  endif()
+endif()
 
 option(USB_SERIAL "Use USB serial instead of UART" OFF)
 

README.md

@@ -3,10 +3,25 @@
 This project uses a Raspberry Pi Pico to identify and store various information
 about a system/fixture, settable and retrievable over UART or USB. Additionally,
 writing can be disabled by jumping GPIO pins 14 and 15 together (pins 19 and 20
-on the board).
+on the board), and GPIO 13 (pin 17 on the board) can be switched to GND and used
+as a pulse counter, such as for a fixture lid switch. This pin is active low and
+counts any low pulse longer than a minimum time period (configurable by with a
+CMake variable).
 
-**Pre-built UF2 files ready to flash onto the Pico for both USB and UART are
-available [here](https://github.com/BloomyControls/pico-ident/releases).**
+This project makes use of a Pi Pico and a MIKROE EEPROM 3 Click. The I2C lines
+for the EEPROM should be connected to GPIOs 16 (SDA) and 17 (SCL) (pins 21 and
+22 on the board, respectively).
+
+**Pre-build UF2 binaries are available for USB or UART configurations
+[here][releases].**
+
+> [!IMPORTANT]
+> This is the new version with pulse counting using the AT24CM02 I2C EEPROM
+> chip. For the old version without pulse counting which uses only the Pico's
+> on-board flash, use [version 1.3.0][1.3.0].
+
+[releases]: https://github.com/BloomyControls/pico-ident/releases
+[1.3.0]: https://github.com/BloomyControls/pico-ident/releases/tag/v1.3.0
 
 ## Information Fields
 
@@ -15,12 +30,12 @@ read the Pico's unique 64-bit identifier as a hex string, but of course this is
 read-only. The idea is that the Pico's serial number can always be used to
 uniquely identify any device, as no two Picos have the same serial.
 
-It's worth noting that each sector (4096 bytes) of flash has a guaranteed
-minimum of 100,000 program-erase cycles according to the manufacturer. Each
-write to one of these fields will incur one erase and one program. This
-effectively limits us to 100,000 writes to any of these fields. Of course, the
-intended use of this device is to be set once and then write-locked for the rest
-of its lifespan, so that's likely not a huge concern here.
+The EEPROM specifies up to 1,000,000 writes per flash cell (per 4-byte word).
+Using a simple wear-leveling scheme using 16 words, the theoretical minimum
+number of pulses that can be counted without resetting is about 16 million. This
+is expected to be incredibly high for most applications, but by changing
+a constant, this number can be trivially increased for more demanding
+applications.
 
 | Field | Access | Description |
 |---|---|---|
@@ -35,6 +50,7 @@ of its lifespan, so that's likely not a huge concern here.
 | `USER3` | Read-write | General-purpose field 3 |
 | `USER4` | Read-write | General-purpose field 4 |
 | `SERIAL` | Read-only | Pico's unique 64-bit serial number |
+| `PULSECOUNT?` | Read-only | Low pulse count on GP13 (board pin 17) |
 
 Note that each of the above fields has a maximum length of 63. Each field is 64
 bytes, but is null-terminated. Values longer than 63 bytes will be truncated.
@@ -61,12 +77,13 @@ to query the manufacturer:
 MFG?\r
 ```
 
-There are two additional commands:
+There are some additional commands:
 
 | Command | Description |
 |---|---|
 | `CLEAR` | Clear all writable fields |
-| `CHECK?` | Check that the data stored in flash matches the stored checksum, then return either `OK` or `ERR` |
+| `CHECK?` | Check that the data stored in EEPROM matches the stored checksum, then return either `OK` or `ERR` |
+| `RESETCOUNT` | Reset the pulse count to 0 |
 
 ## Build Requirements
 
@@ -92,6 +109,10 @@ This step may take quite some time, as it will download the Pi Pico SDK. If you
 wish to use USB for serial communications instead of UART, add `-DUSB_SERIAL=ON`
 to the above command.
 
+The default minimum pulse width is 100ms. To override this time limit, pass
+`-DMIN_PULSE_WIDTH_US=500000` to get 500ms (you can use any whole number of
+microseconds greater than or equal to 50,000).
+
 After the configuration step is done, you can build the project like so:
 
 ```

src/AT24CM02.cpp

@@ -0,0 +1,94 @@
+/*
+ * AT24CM02 Driver Code
+ *
+ * Copyright (c) 2025, Bloomy Controls, Inc. All rights reserved.
+ * Use of this source code is governed by a BSD-3-clause license that can be
+ * found in the LICENSE file or at https://opensource.org/license/BSD-3-Clause
+ */
+
+#include "AT24CM02.h"
+
+#include <algorithm>
+
+constexpr static std::uint32_t kAddrMask{(1U << 18U) - 1U};
+
+AT24CM02::AT24CM02(::i2c_inst_t* i2c, bool addr_pin) noexcept
+    : i2c_{i2c}, addr_pin_(addr_pin ? 1U : 0U) {}
+
+bool AT24CM02::Write(std::uint32_t addr, const std::uint8_t* buf,
+                     std::size_t len) const noexcept {
+  if (!i2c_ || !buf || len == 0 || (addr & ~kAddrMask)) {
+    return false;
+  }
+
+  if (addr + len >= kPages * kBytesPerPage) {
+    return false;
+  }
+
+  std::size_t page_remain = kBytesPerPage - (addr % kBytesPerPage);
+
+  if (len < page_remain) {
+    page_remain = len;
+  }
+
+  while (len > 0) {
+    const std::uint8_t i2c_addr =
+        (0xA0 | (addr_pin_ << 3U) | (addr >> 15U)) >> 1U;
+    std::uint8_t addr_bytes[2];
+
+    addr_bytes[0] = (addr & 0x0FF00) >> 8;
+    addr_bytes[1] = addr & 0x000FF;
+
+    if (::i2c_write_burst_blocking(i2c_, i2c_addr, addr_bytes,
+                                   sizeof(addr_bytes)) == PICO_ERROR_GENERIC) {
+      return false;
+    }
+
+    if (::i2c_write_blocking(i2c_, i2c_addr, buf, page_remain, false) ==
+        PICO_ERROR_GENERIC) {
+      return false;
+    }
+
+    // this could be replaced with ACK polling if we hate waiting for the max
+    // write time
+    ::sleep_ms(10);
+
+    addr += page_remain;
+    buf += page_remain;
+    len -= page_remain;
+
+    page_remain = std::min(len, kBytesPerPage);
+  }
+
+  return true;
+}
+
+bool AT24CM02::Read(std::uint32_t addr, std::uint8_t* buf,
+                    std::size_t len) const noexcept {
+  if (!i2c_ || !buf || len == 0 || (addr & ~kAddrMask)) {
+    return false;
+  }
+
+  if (addr + len >= kPages * kBytesPerPage) {
+    return false;
+  }
+
+  const std::uint8_t i2c_addr =
+      (0xA0 | (addr_pin_ << 3U) | (addr >> 15U)) >> 1U;
+  std::uint8_t addr_bytes[2];
+
+  addr_bytes[0] = (addr & 0x0FF00) >> 8;
+  addr_bytes[1] = addr & 0x000FF;
+
+  if (::i2c_write_blocking(i2c_, i2c_addr, addr_bytes, sizeof(addr_bytes),
+                           true) == PICO_ERROR_GENERIC) {
+    return false;
+  }
+
+  if (::i2c_read_blocking(i2c_, i2c_addr, buf, len, false) ==
+      PICO_ERROR_GENERIC) {
+    return false;
+  }
+
+  return true;
+}

src/AT24CM02.h

@@ -0,0 +1,70 @@
+/*
+ * AT24CM02 I2C Driver
+ *
+ * Copyright (c) 2025, Bloomy Controls, Inc. All rights reserved.
+ * Use of this source code is governed by a BSD-3-clause license that can be
+ * found in the LICENSE file or at https://opensource.org/license/BSD-3-Clause
+ */
+
+#ifndef PICO_IDENT_SRC_AT24CM02_H
+#define PICO_IDENT_SRC_AT24CM02_H
+
+#include <cstddef>
+#include <cstdint>
+
+#include "hardware/i2c.h"
+
+/**
+ * @brief Driver for AT24CM02 I2C EEPROM chip.
+ */
+class AT24CM02 {
+ public:
+  /// Total number of pages in flash.
+  static constexpr std::size_t kPages{1024U};
+  /// Number of bytes per page.
+  static constexpr std::size_t kBytesPerPage{256U};
+
+  /**
+   * @brief Constructor.
+   *
+   * @param[in] i2c I2C instance to use
+   * @param[in] addr_pin state of the A2 pin on the EEPROM chip (high or low)
+   */
+  explicit AT24CM02(::i2c_inst_t* i2c, bool addr_pin) noexcept;
+
+  explicit AT24CM02(std::nullptr_t, bool) = delete;
+
+  /**
+   * @brief Write data to the EEPROM. Does not need to be page-aligned, and may
+   * be longer than a page.
+   *
+   * @param[in] addr 18-bit memory address to write to
+   * @param[in] buf data to write to memory
+   * @param[in] len length of data in bytes
+   *
+   * @return Whether the write was successful.
+   */
+  bool Write(std::uint32_t addr, const std::uint8_t* buf,
+             std::size_t len) const noexcept;
+
+  /**
+   * @brief Read data from the EEPROM. Does not need to be page-aligned, and may
+   * be longer than a page.
+   *
+   * @param[in] addr 18-bit memory address to write to
+   * @param[out] buf buffer to write data into
+   * @param[in] len number of bytes to read
+   *
+   * @return Whether the read was successful.
+   */
+  bool Read(std::uint32_t addr, std::uint8_t* buf,
+            std::size_t len) const noexcept;
+
+ private:
+  /// State of the address pin on the chip.
+  const std::uint8_t addr_pin_;
+  /// I2C instance.
+  ::i2c_inst_t* i2c_;
+};
+
+#endif /* PICO_IDENT_SRC_AT24CM02_H */