{"id":29014618,"url":"https://github.com/armmbed/mbed-os-example-blockdevice","last_synced_at":"2025-07-31T11:14:09.370Z","repository":{"id":33884894,"uuid":"134781547","full_name":"ARMmbed/mbed-os-example-blockdevice","owner":"ARMmbed","description":"The Mbed OS block device example","archived":false,"fork":false,"pushed_at":"2023-02-28T15:22:35.000Z","size":98,"stargazers_count":5,"open_issues_count":0,"forks_count":17,"subscribers_count":86,"default_branch":"master","last_synced_at":"2025-06-25T20:13:53.102Z","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":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ARMmbed.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","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,"zenodo":null}},"created_at":"2018-05-25T00:13:10.000Z","updated_at":"2023-12-04T16:51:08.000Z","dependencies_parsed_at":"2025-06-25T20:13:55.427Z","dependency_job_id":"e224e9c6-90fa-4d84-a4a6-8e3947aa0ccf","html_url":"https://github.com/ARMmbed/mbed-os-example-blockdevice","commit_stats":null,"previous_names":[],"tags_count":57,"template":false,"template_full_name":null,"purl":"pkg:github/ARMmbed/mbed-os-example-blockdevice","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ARMmbed%2Fmbed-os-example-blockdevice","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ARMmbed%2Fmbed-os-example-blockdevice/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ARMmbed%2Fmbed-os-example-blockdevice/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ARMmbed%2Fmbed-os-example-blockdevice/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ARMmbed","download_url":"https://codeload.github.com/ARMmbed/mbed-os-example-blockdevice/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ARMmbed%2Fmbed-os-example-blockdevice/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":268028294,"owners_count":24183811,"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","status":"online","status_checked_at":"2025-07-31T02:00:08.723Z","response_time":66,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":"2025-06-25T20:13:52.600Z","updated_at":"2025-07-31T11:14:09.345Z","avatar_url":"https://github.com/ARMmbed.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"![](./resources/official_armmbed_example_badge.png)\n# Block Device API Mbed OS example\n\nThis example demonstrates how to use a block device as storage on supported [Mbed boards](https://os.mbed.com/platforms/).\n\nYou can build the project with all supported [Mbed OS build tools](https://os.mbed.com/docs/mbed-os/latest/tools/index.html). However, this example project specifically refers to the command-line interface tool [Arm Mbed CLI](https://github.com/ARMmbed/mbed-cli#installing-mbed-cli).\n(Note: To see a rendered example you can import into the Arm Online Compiler, please see our [import quick start](https://os.mbed.com/docs/mbed-os/latest/quick-start/online-with-the-online-compiler.html#importing-the-code).)\n\n\n\n1. [Install Mbed CLI](https://os.mbed.com/docs/mbed-os/latest/quick-start/offline-with-mbed-cli.html).\n1. From the command-line, import the example: `mbed import mbed-os-example-blockdevice`\n1. Change the current directory to where the project was imported: `cd mbed-os-example-blockdevice`\n\n## Application functionality\nThis example demonstrates how to read and write data into a storage device. This can be either an external block device (one of SPI flash, DataFlash or an SD card) or simulated on a heap block device on boards with enough RAM.\n\nBy default, an instance of the SDBlockDevice is used, this requires an external SD card. The [changing the block device](#changing-the-block-device) section describes how to change this. \n\n#### Building and running\n\n1. Connect a USB cable between the USB port on the board and the host computer.\n1. Run the following command to build the example project, program the microcontroller flash memory, and open a serial terminal:\n\n    ```bash\n    mbed compile -m \u003cTARGET\u003e -t \u003cTOOLCHAIN\u003e --flash --sterm\n    ```\n\nAlternatively, you can manually copy the binary to the board, which you mount on the host computer over USB. The binary is located at `./BUILD/\u003cTARGET\u003e/\u003cTOOLCHAIN\u003e/mbed-os-example-blockdevice.bin`.\n\nDepending on the target, you can build the example project with different toolchains. Run the command below to determine which toolchain supports your target:\n```bash\nmbed compile -S\n```\nOnce you have programmed your board, the command line tool should launch a serial console where you will see the applications output. If you don't see anything in the console, restart the program by pressing the reset button on your board.\n\n**Note:** The default serial port baud rate is 9600 bit/s.\n\n## Expected output\n\n``` commandline\n--- Block device geometry ---\nread_size:    1 B\nprogram_size: 1 B\nerase_size:   4096 B\nsize:         4194304 B\n---\nbd.read(0x20000410, 0, 15)\nbd.read -\u003e 0\n--- Stored data ---\nf8 ff ff ff 0f 00 00 00 00 00 00 00 00 00 00\n---\nbd.erase(0, 4096)\nbd.erase -\u003e 0\nbd.program(0x20000410, 0, 15)\nbd.program -\u003e 0\nbd.read(0x20000410, 0, 15)\nbd.read -\u003e 0\n--- Stored data ---\n48 65 6c 6c 6f 20 53 74 6f 72 61 67 65 21 00     Hello Storage!\n---\nbd.deinit()\nbd.deinit -\u003e 0\n--- done! ---\n```\n\nYou can also reset the board to see the data persist across boots:\n\n``` commandline\n--- Block device geometry ---\nread_size:    1 B\nprogram_size: 1 B\nerase_size:   4096 B\nsize:         4194304 B\n---\nbd.read(0x20000410, 0, 15)\nbd.read -\u003e 0\n--- Stored data ---\n48 65 6c 6c 6f 20 53 74 6f 72 61 67 65 21 00     Hello Storage!\n---\nbd.erase(0, 4096)\nbd.erase -\u003e 0\nbd.program(0x20000410, 0, 15)\nbd.program -\u003e 0\nbd.read(0x20000410, 0, 15)\nbd.read -\u003e 0\n--- Stored data ---\n48 65 6c 6c 6f 20 53 74 6f 72 61 67 65 21 00     Hello Storage!\n---\nbd.deinit()\nbd.deinit -\u003e 0\n--- done! ---\n```\n\nTry changing the string \"Hello Storage!\" to a message of your choice to see it\nstored on the block device.\n\n## Troubleshooting\nIf you see garbled text from the read operations check that your SD card is securely fixed in the port. If there's no SD card mounted the application returns garbage characters.  \n\n If you continue to have problems, you can review the [documentation](https://os.mbed.com/docs/latest/tutorials/debugging.html) for suggestions on what could be wrong and how to fix it.\n\n## Changing the block device\nMbed-OS supports a variety of block device types, more information on supported devices can be found [here](https://os.mbed.com/docs/mbed-os/latest/apis/data-storage-concepts.html).\n\nEach device is represented by a C++ class that inherits from the interface class [BlockDevice](https://os.mbed.com/docs/mbed-os/latest/apis/blockdevice-apis.html). These classes take their default configuration from the component configuration file. This may be found in `/mbed-os/storage/blockdevice/` under the path corresponding to the block device type—for example [mbed_lib.json](https://github.com/ARMmbed/mbed-os/blob/master/storage/blockdevice/COMPONENT_SPIF/mbed_lib.json). \n\nIn this example, you can determine which block device is used by modifying the type of `bd` in main.cpp. For instance, if instead you wanted to use a SPIF block device you would declare `bd` as an SPIFBlockDevice instance. \n```diff\n-SDBlockDevice bd(\n-        MBED_CONF_SD_SPI_MOSI,\n-        MBED_CONF_SD_SPI_MISO,\n-        MBED_CONF_SD_SPI_CLK,\n-        MBED_CONF_SD_SPI_CS);\n+SPIFBlockDevice bd(\n+        MBED_CONF_SPIF_DRIVER_SPI_MOSI,\n+        MBED_CONF_SPIF_DRIVER_SPI_MISO,\n+        MBED_CONF_SPIF_DRIVER_SPI_CLK,\n+        MBED_CONF_SPIF_DRIVER_SPI_CS);\n```\nYou may need to make modifications to the application configuration file if you're using a physical storage device that isn't included in your target's default configuration (check in `targets.json` for this). To do this, add your physical storage device as a component in `mbed_app.json` as follows:\n``` json\n   \"target_overrides\": {\n         \"K64F\": {\n             \"target.components_add\": [\"SPIF\"],\n         }\n     }\n```\nYou can also modify the pin assignments for your component as follows:\n``` json\n   \"target_overrides\": {\n         \"K64F\": {\n             \"target.components_add\": [\"SPIF\"],\n             \"spif-driver.SPI_MOSI\": \"PC_12\",\n             \"spif-driver.SPI_MISO\": \"PC_11\",\n             \"spif-driver.SPI_CLK\":  \"PC_10\",\n             \"spif-driver.SPI_CS\":   \"PA_15\"\n         }\n     }\n```\nAlternatively, you may use the system's default block device `BlockDevice *bd = BlockDevice::get_default_instance()` but this will require more code changes to the example.\n## Tested configurations\n- K64F + Heap\n- K64F + SD\n- K64F + SPIF (requires shield)\n- K64F + DataFlash (requires shield)\n- UBLOX_EVK_ODIN_W2 \\[1\\] + Heap\n- UBLOX_EVK_ODIN_W2 \\[1\\] + SD\n- UBLOX_EVK_ODIN_W2 \\[1\\] + SPIF (requires shield)\n- UBLOX_EVK_ODIN_W2 \\[1\\] + DataFlash (requires shield)\n- NUCLEO_F429ZI + Heap\n- NUCLEO_F429ZI + SD (requires shield)\n- NUCLEO_F429ZI + SPIF (requires shield)\n- NUCLEO_F429ZI + DataFlash (requires shield)\n- DISCO_L475VG_IOT01A + QSPIF\n- DISCO_L476VG + QSPIF\n- DISCO_F413ZH + QSPIF\n- DISCO_F469NI + QSPIF\n\n\\[1\\]: Note: The UBLOX_EVK_ODIN_W2 SPI pins conflict with the default serial\npins. A different set of serial pins must be selected to use SPI flash with\nserial output.\n\n``` c++\n// Connect Tx, Rx, and ground pins to a separte board running the passthrough example:\n// https://os.mbed.com/users/sarahmarshy/code/SerialPassthrough/file/2a3a62ee17fa/main.cpp/\nSerial pc(TX, RX);   \n\npc.printf(\"...\");    // Replace printf with pc.printf in the example\n```\n### License and contributions\n\nThe software is provided under Apache-2.0 license. Contributions to this project are accepted under the same license. Please see [contributing.md](CONTRIBUTING.md) for more info.\n\nThis project contains code from other projects. The original license text is included in those source files. They must comply with our license guide.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farmmbed%2Fmbed-os-example-blockdevice","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Farmmbed%2Fmbed-os-example-blockdevice","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farmmbed%2Fmbed-os-example-blockdevice/lists"}