EEPROM Handler

The EepromHandler is used to store Node and application data, currently in an 'external' I²C EEPROM. It is noted that some MCUs include their own EEPROMs, or pseudo-EEPROMs, and while these alternatives are not currently supported, there is no reason why the EerpomHandler could not be extended to manage these alternatives in a seamless fashion. The primary purpose of this and the other 'Handlers' is to remove the need to consider the details of common underlying processes in the development of individual applications.

While EERPOMs of greater capacity are generally used (because there are little or no cost implications), the data structure overlay currently managed by the EepromHandler comprises only 256 bytes, as illustrated below. This is, nonetheless, the maximum capacity that can be accessed through a single I²C device address on an EEPROM of 16K or less (refer to the discussion on addressing in the following section).

Langlo EEPROM Data Structure.docx

[92 KB]

EEPROM Addressing

Accessing higher capacity (>16K) I²C EEPROMs is complicated somewhat by the addressing characteristics of the I²C bus. In the present case, there were several issues that required consideration in developing methods that could accommodate EEPROMs of different sizes.

First of all, while the size of an EEPROM is generally measured in bits (e.g. an 8K EEPROM comprises 8K bits, or 1K bytes of storage), its contents are accessed using byte offsets. Even so, a 'standard' internal address is limited to just 8 bits, so that only 256 bytes are directly addressable. To manage this issue, EEPROMs of more than 2K bits (256 bytes), up to 16K, are effectively addressed in 256 byte blocks identified by unique I²C device addresses—the first by address 0x50, the second 0x51, etc.

There is a side note to be made here in relation to configuring more than one EEPROM on a single I²C bus. This is permitted, using the appropriate hardware configuration, provided no more than 16Kbits of EEPROM in total are configured (when using 'standard', single byte internal addressing). These 16Kbits of EEPROM are then addressed as eight discrete 2K 'blocks', with I²C device addresses 0x50 – 0x57 respectively. Unfortunately, there is no way for library functions to devine what I²C device address a user might wish to access, so this choice must be managed within the relevant sketch, before invoking the EepromHandler.

An expanded addressing mechanism is required to support EEPROMs larger than 16K, with the result that a 'smart' two-byte internal address must be used on EEPROMs of 32K or more. The trick, from a software perspective, is to be able to determine the size of an EEPROM, or at least the required internal addressing mode, without its being explicitly defined, thus enabling software to be universal with regard to the size of EEPROM that might be configured.

A mechanism to achieve this end, and indeed to automatically determine the size of a configured EEPROM, is described in Microchip Application Note AN690. The process described therein for determining the required addressing mechanism is as follows:

We send a two-byte address, 00 00, followed by a single data byte, 01, to be written to that address, then attempt to read the value back using a single-byte address of 00. If the EEPROM under test requires ('standard') single-byte addressing, we will read a value of 00 at address 00. If ('smart') addressing is required, the original write request will have set the value of the byte at this location to 01.

The logic of this process is as follows:

• Transmitted write request:

  –start– 00 00 01 –stop–

• If a ('standard') single-byte address was required, the write request will have been interpreted as a single address byte, 00, followed by two data bytes, 00 and 01, which will be stored starting, as requested, at location 00.

  Result:

  Location	00	01
  Value	00	01

• If a ('smart') two-byte address was required, the write request will produce its intended outcome, with two address bytes, 0000, identifying the location, followed by a single data byte, 01.

  Result:

  Location	0000	0001
  Value	01	unknown

When we try to read the stored value using a single address byte, 00, the request will be interpreted as follows:

• Transmitted read request:

  –start– 00 –stop–

• If a ('standard') single-byte address is required, the [single byte] address provided will be valid and the content of EEPROM location 00 will be returned as 00 (see above).

• If a ('smart') two-byte address is required, the address in our read request, which contains only a single address byte, will be incomplete, and the result dependent on how the system responds to this condition. The Application Note suggests that, for reasons discussed therein, the request would always return the value at location 0000, which would be 01.

  My own observation has been that, in this situation, the EEPROM address register appears to contain the address following the last valid access request. In fact, on closer inspection, the relevant Microchip [AT24C08, AT24C16, AT24C32] data sheets all state exactly this:

  "The internal data word address counter maintains the last address accessed during the last read or write operation, incremented by one. This address stays valid between operations as long as the chip power is maintained."

  In the present case, the value of the byte at that location, location 0001, is unknown.

In our write process then, we need to ensure that we always write some known value into location 01, or 0001, of the EERPOM, as, if we are careful with our sequence of instructions, this will be the value returned by a read request with an incomplete address specification (i.e. from an EEPROM that requires two-byte addressing). Accordingly, one small modification has been made to the Microchip algorithm. Instead of attempting to write just one byte to a known location, we write two, as follows:

• Send two write requests:

  –start– 00 01 01 –stop–

  –start– 00 00 01 –stop–

• If a ('standard') single-byte address was required, each write request will have been interpreted as a single address byte followed by two data bytes. After the first write, we will have the following:

  Location	00	01
  Value	01	01

  Then, after the second, which overwrites the same two bytes:

  Location	00	01
  Value	00	01

• If a ('smart') two-byte address was required, these write requests will write the value 01 to each of the two distinct addresses specified. After the first write, to location 0001, we will have the following:

  Location	0000	0001
  Value	unknown	01

  Then, after the second, to location 0000:

  Location	0000	0001
  Value	01	01

  The important thing about writing the two locations in this way is that the EERPOM address register is left containing the location following the last write, that being location 01 (or 0001), the content of which we know (see above). If we had simply written two bytes in sequence, the register would be left pointing to the third byte, location 02 (or 0002), the content of which would be unknown.

This process will have no impact on the result if 'standard' single-byte addressing is required—the subsequent read request will return the value stored at location 00, which will be 00.

If, however, 'smart' addressing is required, both EEPROM locations 0000 and 0001 will contain the value 01, which will thus be the value returned whether the incomplete address provided in the 'standard' single-byte address read attempt returns the value stored at location 0000, as suggested by the Microchip Application Note, or the location following that of the last successful operation, 0001, as the datasheets suggest.

It is also noted that this process overwrites the original contents of the first two bytes of the EERPOM. In the present implementation, the relevant EepromHandler class method (setSmartSerial()) saves the original EEPROM contents and restores them on completion of the test, so no data is lost in the process—we save using both addressing methods, noting that only one will produce a valid copy, but which one is valid will be known on completion of the test and it is this copy that is then used in the restoration.

Data Structures and Methods

The central data structure in the EepromHandler defines the arrangement of data elements within the EEPROM. The data elements themelves are itemised in the EH_dataType enumerated type, which can be expanded to accommodate additional elements as required. The size and location within the EEPROM of each of the identified data elements are then defined in appropriate array structures within the EerpomHandler class.

An EEPROM instance is created and initialised using the begin method. Several versions of the method are available, providing varying degrees of initialisation:

An appropriate Wire instance must be created in the parent sketch and identified in the call (see below). By default, the I²C device address is set to 0x50, and the internal addressing mode is set to SmartSerial (two-byte) addressing (i.e. by default, an EEPROM of 32K or more is assumed), but either, or both of these parameters can also be explicitly specified if required—setting the Mode Flag to true enables two-byte addressing (set by default in any case), and false enables 'standard' (single-byte) addressing.

Methods are provided to enable parameters to be set or reset, if and as appropriate, at any point within a sketch:

Calling the setSmartSerial() function without any parameters executes the algorithm discussed above to automatically set the type of addressing required, returning true if two-byte addressing has been set or false otherwise.

Methods are also provided to query internal parameter settings:

Then we have the workhorse methods to write data to, and read data from EEPROM:

The write() and read() methods provide the ability to write and read arbitrary byte streams to arbitrary EEPROM locations. The more specific write and read methods are provided to simplify the process of writing and reading specific data types to predefined locations associated with the specified EH_dataType (see definition above).

Finally there are methods to generate a HEX dump of, or 'scrub' (reset to all-1s) the current contents of the EEPROM:

The dump() and scrub() methods currently only operate on the first 256 bytes of an EEPROM (that's all the EepromHandler uses), although this applies to any EEPROM segment that is addressed through a unique I²C device address. If only a subset of this block is required, the relevant start and end bytes can be specified.

Usage

Note that, as stated in the Microchip AT24C32/AT24C64 datasheet, when these EEPROMs are powered with less than 5V, the I²C bus should not be clocked above 100kHz. I've not had problems using a higher rate (400kHz) in conjunction with the Espressif MCUs, but my experience has been that this limitation must be observed when using the 3.3V Pro Mini.

Typical usage of the EepromHandler class and methods is illustrated in the following pseudo-sketch.