{"id":21424951,"url":"https://github.com/arkhipenko/esp32himem","last_synced_at":"2026-03-05T01:33:52.922Z","repository":{"id":49331905,"uuid":"386057503","full_name":"arkhipenko/ESP32Himem","owner":"arkhipenko","description":null,"archived":false,"fork":false,"pushed_at":"2022-04-10T01:18:49.000Z","size":25,"stargazers_count":13,"open_issues_count":1,"forks_count":2,"subscribers_count":1,"default_branch":"master","last_synced_at":"2026-01-30T13:24:49.814Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/arkhipenko.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-07-14T19:41:55.000Z","updated_at":"2025-02-13T22:01:09.000Z","dependencies_parsed_at":"2022-09-12T21:41:09.042Z","dependency_job_id":null,"html_url":"https://github.com/arkhipenko/ESP32Himem","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/arkhipenko/ESP32Himem","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arkhipenko%2FESP32Himem","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arkhipenko%2FESP32Himem/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arkhipenko%2FESP32Himem/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arkhipenko%2FESP32Himem/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/arkhipenko","download_url":"https://codeload.github.com/arkhipenko/ESP32Himem/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arkhipenko%2FESP32Himem/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30104529,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-05T01:06:53.091Z","status":"ssl_error","status_checked_at":"2026-03-05T01:02:35.679Z","response_time":59,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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-11-22T21:25:54.029Z","updated_at":"2026-03-05T01:33:47.910Z","avatar_url":"https://github.com/arkhipenko.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ESP32 Himem\n### Access to HIMEM area on ESP32 microcontrollers from Arduino Core as Stream\n#### Version 0.0.4: 2022-04-09 \n\n### OVERVIEW:\nSome ESP32 modules come equipped with PSRAM, and some even have 8 MB of it.\n\nUnfortunately only 4 MB of PSRAM is available via standard PSRAM API.\n\nThe \"high\" 4 MB area requires use of the Espressif's **HIMEM** **API** which (as of Arduino Core 1.0.6) does not work with Arduino Core.\n\nThis library breaks that spell and makes the 4 MB of himem area available as a class derived from **Stream** so you can easily use those megabytes as file store or as a memory array. \n\nAPI definition is fairly straightforward and all memory remapping is happening behind the scenes. \n\nBecause of the memory remapping the access is rather slow (especially random), so consider this to be a 4 MB fast HDD for ESP32 :)\n\n\n\n### API\n\n    ESP32Himem();\n    virtual ~ESP32Himem();\n      \n    virtual int       begin(size_t ranges, bool option); // ranges: 1-8, default 8, option (see below)\n    \n    virtual int       available();\n    virtual int       read();\n    virtual size_t    write(uint8_t data);\n    virtual int       peek();\n    virtual void      flush();\n    virtual size_t    size();\n    \n    virtual size_t    physSize()};\n    virtual int       seek(size_t position);\n    virtual uint8_t\u0026  operator[](size_t pos);\n    size_t            bufferSize();\n    size_t            bufferIndex();\n    uint8_t*          pointer();\n\n\n### Note on direct memory access:\n\nAfter your index been positioned and mapped, it is placed inside the mapped memory area according to your mapping strategy option of the `himem.begin()` method (see below). Range allocation has to observe the 32KB alignments and be mapped to an area from 32,768 of up to 262,144 bytes long.\n\nTechnically you can address that memory region directly and read/write to that area directly as you would to regular RAM.\n\nYour data is located at `pointer()` position in physical address space of ESP32 memory.\n\nYou have `bufferSize() - bufferIndex() - 1` bytes of memory available to the **right** of the pointer and `bufferIndex()` bytes available to the **left** of the pointer. **Be careful.** \n\n\n### Note on PSRAM\n\nThe address space used by PSRAM API and HIMEM API is the same, so allocating a window of memory to look into HIMEM area will take away from the available PSRAM. Arduino is configured to use up to 8 x 32KB memory blocks to access HIMEM. In most cases you only need one, so start `himem.begin(1)` to allocate just 32K and lose *only* 32K of PSRAM. 8 ranges will allocate 262144 bytes and that's how much PSRAM you will lose as well. \n\n**ALSO:** please initialize HIMEM before doing any PSRAM memory allocations via `ps_malloc`. I have witnessed values changing as the HIMEM window was allocated on top of previously allocated PSRAM memory range. **Be careful.** \n\n### Note on Range Allocation Option parameter of begin() method\n\nBy default, ESP32Himem allocates the maximum available number of memory ranges (8) to access parts of himem area. That gives you a \"window\" of 262,144 bytes. Since an your index (the current address of the memory being accessed) could fall into any of the 8 standard 32K ranges, there are two separate mapping strategies possible:\n\n1. Map as close to the left (lesser) address to allow as much pointer access to the right as the range allows to.\n\n   This option requires more frequent remapping, and therefore takes a little toll on performance as the full range is remapped for every one of the 8 standard 32K ranges. This is a default option, and could be achieved by using `himem.begin(8);` (or any other number between 1-8) or `himem.begin(8, ESP32HIMEM_REMAP_MORE);`\n\n   Using this option guarantees that you have at least `(N-1)*32K` bytes of memory to the right of the pointer, where N is the total number or standard ranges allocated (1-8). \n\n2. Map anywhere within the full range. The \"catch\" here is that the pointer could be anywhere within the range, including at the very far right end of it, which makes use of pointer less efficient, but requires fewer remaps, so improves performance slightly. \n\n   To use this remap strategy start ESP32Himem with `himem(8, ESP32HIMEM_REMAP_LESS);` option.\n\n### Note on Out-of-Bounds checking\n\nBy default every range remap operation is checking if the index is out of bounds of available memory. This takes a few microseconds. If you are absolutely sure in your ability to manage the range properly, you can compile the library with\n`#define ESP32HIMEM_NO_RANGE_CHECK` compile option and gain a little performance improvement at a price of potential error. Up to you. **Be careful with this one.** \n\n### Benchmarking (default setup)\n\n```\nHimem physical size: 4456448\nHimem allocated size: 4456448\nHimem max buffer size: 262144\nHimem pointer: 3FBC0000\n\nPopulating Himem area... \nStart time: 835\nStop  time: 4873\n\nReading Himem area via Read \nStart time: 4873\nStop  time: 8507\n\nReading Himem area via [] \nStart time: 8508\nStop  time: 11473\n\nReading Himem area randomly 1000 times \nStart time: 11473\nStop  time: 21794\n\nWriting and reading Himem area buffer directly \nStart time: 21794\nStop  time: 21827\n```\n\nSee example for details. \n\n### How to use with PlatformIO\n\nInstead of including `\u003cESP32Himem.h\u003e` into your Arduino sketches, include `\u003cESP32HimemDeclarations.h\"` instead.\nIn your project source folder, create a ile `ESP32Himem.cpp` with this one line of contents:\n\nESP32Himem.cpp:\n\n#include \u003cESP32Himem.h\u003e\n\n\n\nThat's it. \n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farkhipenko%2Fesp32himem","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Farkhipenko%2Fesp32himem","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farkhipenko%2Fesp32himem/lists"}