diff options
| -rw-r--r-- | src/storage.h | 111 |
1 files changed, 98 insertions, 13 deletions
diff --git a/src/storage.h b/src/storage.h index cf66730..6b76190 100644 --- a/src/storage.h +++ b/src/storage.h @@ -14,16 +14,26 @@ class Storage { private: + /** + * Number of animations on the storage, AKA contents of byte 0x0000. + * A value of 0xff indicates that the EEPROM was never written to + * and therefore contains no animations. + */ uint8_t num_anims; + + /** + * Page offset of the pattern read by the last load() call. Used to + * calculate the read address in loadChunk(). The animation this + * offset refers to starts at byte 256 + (32 * page_offset). + */ uint8_t page_offset; + + /** + * First free page (excluding the 256 byte metadata area) on the + * EEPROM. Used by save() and append(). This value refers to the + * EEPROM bytes 256 + (32 * first_free_page) and up. + */ uint8_t first_free_page; - uint8_t i2c_start_write(void); - uint8_t i2c_start_read(void); - void i2c_stop(void); - uint8_t i2c_send(uint8_t len, uint8_t *data); - uint8_t i2c_receive(uint8_t len, uint8_t *data); - uint8_t i2c_read(uint8_t addrhi, uint8_t addrlo, uint8_t len, uint8_t *data); - uint8_t i2c_write(uint8_t addrhi, uint8_t addrlo, uint8_t len, uint8_t *data); enum I2CStatus : uint8_t { I2C_OK, @@ -32,13 +42,87 @@ class Storage { I2C_ERR }; + /** + * Sends an I2C start condition and the I2C_EEPROM_ADDR with the + * write flag set. + * + * @return An I2CStatus value indicating success/failure + */ + uint8_t i2c_start_write(void); + + /** + * Sends an I2C start condition and the I2C_EEPROM_ADDR with the + * read flag set. + * + * @return An I2CStatus value indicating success/failure + */ + uint8_t i2c_start_read(void); + + /** + * Sends an I2C stop condition. Does not check for errors. + */ + void i2c_stop(void); + + /** + * Sends up to len bytes of data via I2C. i2c_start_write() must + * have been called successfully for this to work. + * + * @param len number of bytes to send + * @param data pointer to data buffer, must be at least len bytes + * @return number of bytes which were successfully sent (0 .. len) + */ + uint8_t i2c_send(uint8_t len, uint8_t *data); + + /** + * Receives up to len bytes of data via I2C. i2c_start_read() must + * have been called successfully for this to work. + * + * @param len number of bytes to receive + * @param data pointer to data buffer, must be at least len bytes + * @return number of bytes which were successfully received (0 .. len) + */ + uint8_t i2c_receive(uint8_t len, uint8_t *data); + + /** + * Reads len bytes of data stored on addrhi, addrlo from the EEPROM + * into the data buffer. Does a complete I2C transaction including + * start and stop conditions. addrlo may start at an arbitrary + * position, page boundaries are irrelevant for this function. If a + * read reaches the end of the EEPROM memory, it will wrap around to + * byte 0x0000. + * + * @param addrhi upper address byte. Must be less than 32 + * @param addrlo lower address byte + * @param len number of bytes to read + * @param data pointer to data buffer, must be at least len bytes + * @return An I2CStatus value indicating success/failure + */ + uint8_t i2c_read(uint8_t addrhi, uint8_t addrlo, uint8_t len, uint8_t *data); + + /** + * Writes len bytes of data from the data buffer into addrhi, addrlo + * on the EEPROM. Does a complete I2C transaction including start and + * stop conditions. Note that the EEPROM consists of 32 byte pages, + * so it is not possible to write more than 32 bytes in one + * operation. Also note that this function does not check for page + * boundaries. Starting a 32-byte write in the middle of a page will + * put the first 16 bytes where they belong, while the second 16 + * bytes will wrap around to the first 16 bytes of the page. + * + * @param addrhi upper address byte. Must be less than 32 + * @param addrlo lower address byte + * @param len number of bytes to write + * @param data pointer to data buffer, must be at least len bytes + * @return An I2CStatus value indicating success/failure + */ + uint8_t i2c_write(uint8_t addrhi, uint8_t addrlo, uint8_t len, uint8_t *data); + public: Storage() { num_anims = 0; first_free_page = 0;}; /** - * Enable the storage hardware: Configures the internal I2C - * module and reads the number of stored patterns from the - * EEPROM. + * Enables the storage hardware: Configures the internal I2C + * module and reads num_anims from the EEPROM. */ void enable(); @@ -68,17 +152,18 @@ class Storage { /** * Accessor for the number of saved patterns on the EEPROM. - * Only returns valid data if hasData() returned true. + * A return value of 255 (0xff) means that there are no patterns + * on the EEPROM (and hasData() returns false in that case). * * @return number of patterns */ uint8_t numPatterns() { return num_anims; }; /** - * Load pattern from EEPROM. + * Loads pattern number idx from the EEPROM. The * * @param idx pattern index (starting with 0) - * @param data pointer to data structure for the pattern. Must be + * @param pointer to the data structure for the pattern. Must be * at least 132 bytes */ void load(uint8_t idx, uint8_t *data); |