{"id":13802637,"url":"https://github.com/peterhinch/micropython_eeprom","last_synced_at":"2025-04-23T02:07:25.505Z","repository":{"id":37443414,"uuid":"227298074","full_name":"peterhinch/micropython_eeprom","owner":"peterhinch","description":"MicroPython device drivers for memory chips (EEPROM, FRAM, Flash, SPIRAM)","archived":false,"fork":false,"pushed_at":"2024-09-29T11:01:57.000Z","size":159,"stargazers_count":80,"open_issues_count":7,"forks_count":34,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-04-23T02:07:21.962Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/peterhinch.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-12-11T06:59:31.000Z","updated_at":"2025-02-24T18:46:25.000Z","dependencies_parsed_at":"2024-12-17T00:21:32.211Z","dependency_job_id":null,"html_url":"https://github.com/peterhinch/micropython_eeprom","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peterhinch%2Fmicropython_eeprom","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peterhinch%2Fmicropython_eeprom/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peterhinch%2Fmicropython_eeprom/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peterhinch%2Fmicropython_eeprom/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/peterhinch","download_url":"https://codeload.github.com/peterhinch/micropython_eeprom/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250354507,"owners_count":21416752,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-04T00:01:49.101Z","updated_at":"2025-04-23T02:07:25.489Z","avatar_url":"https://github.com/peterhinch.png","language":"Python","readme":"# 1. MicroPython drivers for memory chips\n\nThese drivers support either byte level access or the littlefs filesystem.\nSupported technologies are Flash, EEPROM, FRAM and SPIRAM.\n\nCurrently supported devices include technologies having superior performance\ncompared to flash. Resultant storage has much higher write endurance. In some\ncases read and write access times may be shorter. EEPROM and FRAM chips have\nmuch lower standby current than SD cards, benefiting micropower applications.\n\nThe drivers present a common API having the features listed below.\n\n## 1.1 Features common to all drivers\n\nThe drivers have the following common features:\n 1. Support for single or multiple chips on the same bus. Multiple chips are\n automatically configured as a single array.\n 2. This can be accessed as an array of bytes, using Python slice syntax or via\n a `readwrite` method.\n 3. Alternatively the array can be formatted and mounted as a filesystem using\n methods in the `os` module. Any filesystem supported by the MicroPython build\n may be employed: FAT and littlefs have been tested. The latter is recommended.\n 4. Drivers are portable: buses and pins should be instantiated using the\n `machine` module.\n 5. Buses may be shared with other hardware. This assumes that the application\n pays due accord to differing electrical constraints such as baudrate.\n\n## 1.2 Technologies\n\nCurrently supported technologies are SPIRAM (PSRAM), Flash, EEPROM, and FRAM\n(ferroelectric RAM). The latter two are nonvolatile random access storage\ndevices with much higher endurance than flash memory. Flash has a typical\nendurance of 10-100K writes per page. The figures for EEPROM and FRAM are 1-4M\nand 10^12 writes respectively. In the case of the FAT filing system 1M page\nwrites probably corresponds to 1M filesystem writes because FAT repeatedly\nupdates the allocation tables in the low numbered sectors. Under `littlefs` I\nwould expect the endurance to be substantially better owing to its wear\nlevelling architecture; over-provisioning should enhance this.\n\nSPIRAM has huge capacity and effectively infinite endurance. Unlike the other\ntechnologies it is volatile: contents are lost after a power cycle.\n\n## 1.3 Organisation of this repo\n\nThe directory structure is `technology/interface` where supported chips for a\ngiven technology offer SPI and I2C interfaces; where only one interface exists\nthe `interface` subdirectory is omitted. The file `bdevice.py` is common to all\ndrivers and is in the root directory.\n\nThe link in the table below points to the docs relevant to the specific chip.\nIn that directory may be found test scripts which may need minor adaptation for\nthe host and interface in use. It is recommended to run these to verify the\nhardware configuration.\n\n## 1.4 Supported chips\n\nThese currently include Microchip and STM EEPROM chips and\n[this Adafruit FRAM board](http://www.adafruit.com/product/1895). Note that the\nlargest EEPROM chip uses SPI: see [below](./README.md#2-choice-of-interface)\nfor a discussion of the merits and drawbacks of each interface.\n\nThe EEPROM drivers have been updated to be generic. Page size can be auto\ndetected and the drivers have been tested with a wide variety of chips in sizes\nfrom 256 bytes to 256KiB. Thanks are due to Abel Deuring for doing much of this\ntesting. That said, it is not possible to guarantee that all possible device\ntypes will work.\n\nSupported devices. Microchip manufacture each chip in different variants with\nletters denoted by \"xx\" below. The variants cover parameters such as minimum\nVcc value and do not affect the API. There are two variants of the STM chip,\nM95M02-DRMN6TP and M95M02-DWMN3TP/K. The latter has a wider temperature range.\n\nThe interface column includes page size where relevant. The EEPROM driver can\nauto-detect this and report it for a given chip.\n\n| Manufacturer | Part      | Interface | Bytes   | Technology | Docs                          |\n|:------------:|:---------:|:---------:|:-------:|:----------:|:-----------------------------:|\n| Various      | Various   | SPI 4096  | \u003c=32MiB |   Flash    | [FLASH.md](./flash/FLASH.md)  |\n| STM          | M95M02-DR | SPI       | 256KiB  |   EEPROM   | [SPI.md](./eeprom/spi/SPI.md) |\n| Microchip    | 25xx1024  | SPI       | 128KiB  |   EEPROM   | [SPI.md](./eeprom/spi/SPI.md) |\n| Microchip    | 25xx512*  | SPI       |  64KiB  |   EEPROM   | [SPI.md](./eeprom/spi/SPI.md) |\n| Microchip    | 24xx512   | I2C       |  64KiB  |   EEPROM   | [I2C.md](./eeprom/i2c/I2C.md) |\n| Microchip    | 24xx256   | I2C       |  32KiB  |   EEPROM   | [I2C.md](./eeprom/i2c/I2C.md) |\n| Microchip    | 24xx128   | I2C       |  16KiB  |   EEPROM   | [I2C.md](./eeprom/i2c/I2C.md) |\n| Microchip    | 24xx64    | I2C       |   8KiB  |   EEPROM   | [I2C.md](./eeprom/i2c/I2C.md) |\n| Microchip    | 24xx32    | I2C       |   4KiB  |   EEPROM   | [I2C.md](./eeprom/i2c/I2C.md) |\n| Adafruit     | 4719      | SPI n/a   | 512KiB  |   FRAM     | [FRAM_SPI.md](./fram/FRAM_SPI.md) |\n| Adafruit     | 4718      | SPI n/a   | 256KiB  |   FRAM     | [FRAM_SPI.md](./fram/FRAM_SPI.md) |\n| Adafruit     | 1895      | I2C n/a   |  32KiB  |   FRAM     | [FRAM.md](./fram/FRAM.md)     |\n| Adafruit     | 4677      | SPI n/a   |   8MiB  |   SPIRAM   | [SPIRAM.md](./spiram/SPIRAM.md) |\n\nParts marked * have been tested by users (see below).  \nThe SPIRAM chip is equivalent to Espressif ESP-PSRAM64H.\n\nThe flash driver now has the capability to support a variety of chips. The\nfollowing have been tested to date:\n\n| Chip              | Size (MiB) |\n|:-----------------:|:----------:|\n| Cypress S25FL256L | 32         |\n| Cypress S25FL128L | 16         |\n| Cypress S25FL064L |  8         |\n| Winbond W25Q32JV  |  4         |\n\n\nIt is likely that other chips with 4096 byte blocks will work but I am unlikely\nto be able to support hardware I don't possess. Users should check datasheets\nfor compatibility.\n\n### 1.4.1 Chips tested by users\n\nIf you have success with other chips please raise an issue and I will update\nthis doc. Please note the `cmd5` arg. It is essential to know whether a chip\nuses 4 or 5 byte commands and to set this correctly otherise very confusing\nbehaviour results.\n\nCAT24C256LI-G I2C EEPROM 32KiB tested by\n[Julien Phalip](https://github.com/peterhinch/micropython_eeprom/issues/6#issuecomment-825801065).\n\nWinbond W25Q128JV Flash 16MiB tested by\n[mweber-bg](https://github.com/peterhinch/micropython_eeprom/issues/8#issuecomment-917603913).  \nThis requires setting `cmd5=False`.\n\nWinbond W25Q64JV Flash 8MiB tested by\n[IlysvlVEizbr](https://github.com/peterhinch/micropython_eeprom/issues/17).  \nThis requires setting `cmd5=False`.\n\nMicrochip 25LC512 SPI EEPROM 64KiB tested by\n[ph1lj-6321](https://github.com/peterhinch/micropython_eeprom/issues/10).\n\n## 1.5 Performance\n\nFRAM and SPIRAM are truly byte-addressable: speed is limited only by the speed\nof the I2C or SPI interface (SPI being much faster).\n\nReading from EEPROM chips is fast. Writing is slower, typically around 5ms.\nHowever where multiple bytes are written, that 5ms applies to a page of data so\nthe mean time per byte is quicker by a factor of the page size (128 or 256\nbytes depending on the device).\n\nThe drivers provide the benefit of page writing in a way which is transparent.\nIf you write a block of data to an arbitrary address, page writes will be used\nto minimise total time.\n\nIn the case of flash, page writing is mandatory: a sector is written by first\nerasing it, a process which is slow. This physical limitation means that the\ndriver must buffer an entire 4096 byte sector. This contrasts with FRAM and\nEEPROM drivers where the buffering comprises a few bytes.\n\n# 2. Choice of interface\n\nThe principal merit of I2C is to minimise pin count. It uses two pins\nregardless of the number of chips connected. It requires pullup resistors on\nthose lines, although these may be provided on the target device. The\nsupported EEPROM devices limit expansion to a maximum of 8 chips on a bus.\n\nSPI requires no pullups, but uses three pins plus one for each connected chip.\nIt is much faster than I2C, but in the case of EEPROMs the benefit is only\napparent on reads: write speed is limited by the EEPROM device. In principle\nexpansion is limited only by the number of available pins. (In practice\nelectrical limits may also apply).\n\nThe larger capacity chips generally use SPI.\n\n# 3. Design details\n\nA key aim of these drivers is support for littlefs. This requires the extended\nblock device protocol as described\n[here](http://docs.micropython.org/en/latest/reference/filesystem.html) and\n[in the uos doc](http://docs.micropython.org/en/latest/library/os.html).\nThis protocol describes a block structured API capable of handling offsets into\nthe block. It is therefore necessary for the device driver to deal with any\nblock structuring inherent in the hardware. The device driver must enable\naccess to varying amounts of data at arbitrary physical addresses.\n\nThese drivers achieve this by implementing a device-dependent `readwrite`\nmethod which provides read and write access to arbitrary addresses, with data\nvolumes which can span page and chip boundaries. A benefit of this is that the\narray of chips can be presented as a large byte array. This array is accessible\nby Python slice notation: behaviour provided by the hardware-independent base\nclass.\n\nA consequence of the above is that the page size in the ioctl does not have any\nnecessary connection with the memory hardware, so the drivers enable the value\nto be specified as a constructor argument. Littlefs requires a minimum size of\n128 bytes -\n[theoretically 104](https://github.com/ARMmbed/littlefs/blob/master/DESIGN.md).\nThe drivers only allow powers of 2: in principle 128 bytes could be used. The\ndefault in MicroPython's littlefs implementation is 512 bytes and all testing\nwas done with this value. FAT requires 512 bytes minimum: FAT testing was done\nwith the same block size.\n\n## 3.1 Developer Documentation\n\nThis [doc](./BASE_CLASSES.md) has information on the base classes for those\nwishing to write drivers for other memory devices.\n\n# 4. Filesystem support\n\nThe test programs use littlefs and therefore require MicroPython V1.12 or\nlater. On platforms that don't support littlefs the options are either to adapt\nthe test programs for FAT (code is commented out) or to build firmware with\nlittlefs support. This can be done by passing `MICROPY_VFS_LFS2=1` to the\n`make` command.\n\nA filesystem can be mounted in `boot.py`: this enables it to be managed on the\nPC using `rshell` or `mpremote`. Exact details are hardware dependent (see the\nrelevant docs) but a typical `mount.py` is as below, called by the last line in\n`boot.py`:\n```py\nimport os\nfrom machine import SPI, Pin, SoftSPI\nfrom eeprom_spi import EEPROM\nspi = SoftSPI(baudrate=5_000_000, sck=Pin(\"Y6\"), miso=Pin(\"Y7\"), mosi=Pin(\"Y8\"))\ncspins = (Pin(Pin.board.Y5, Pin.OUT, value=1), Pin(Pin.board.Y4, Pin.OUT, value=1))\neep = EEPROM(spi, cspins, 128)\nos.mount(eep, \"/eeprom\")\n```\nThe filesystem may then be accessed as follows:\n```bash\n$ mpremote cp foo.py :/eeprom/\n```\n","funding_links":[],"categories":["Libraries"],"sub_categories":["Storage"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpeterhinch%2Fmicropython_eeprom","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpeterhinch%2Fmicropython_eeprom","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpeterhinch%2Fmicropython_eeprom/lists"}