{"id":13801963,"url":"https://github.com/pulkin/unbd","last_synced_at":"2025-04-19T04:18:59.187Z","repository":{"id":106307573,"uuid":"605520169","full_name":"pulkin/unbd","owner":"pulkin","description":"Micro implementation of network block device (NBD) for micropython","archived":false,"fork":false,"pushed_at":"2023-03-21T14:35:56.000Z","size":80,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-04-22T12:33:27.117Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pulkin.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"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}},"created_at":"2023-02-23T10:31:40.000Z","updated_at":"2024-03-23T17:17:37.000Z","dependencies_parsed_at":"2024-01-07T21:53:13.631Z","dependency_job_id":null,"html_url":"https://github.com/pulkin/unbd","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/pulkin%2Funbd","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pulkin%2Funbd/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pulkin%2Funbd/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pulkin%2Funbd/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pulkin","download_url":"https://codeload.github.com/pulkin/unbd/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":229327737,"owners_count":18055782,"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:31.674Z","updated_at":"2024-12-12T04:11:05.294Z","avatar_url":"https://github.com/pulkin.png","language":"Python","readme":"[![build](https://github.com/pulkin/unbd/actions/workflows/test.yml/badge.svg)](https://github.com/pulkin/unbd/actions)\n[![pypi](https://img.shields.io/pypi/v/unbd)](https://pypi.org/project/unbd/)\n\nunbd\n====\n\n`unbd` - micro implementation of a\n[network block device](https://en.wikipedia.org/wiki/Network_block_device)\nin python.\n\nWhat for?\n---------\n\nUse this package for mounting folders on wifi-enabled micropython\ndevices such as `ESP8266` and `ESP32`.\n\nInstall\n-------\n\nIf you want to use `unbd` directly install it on\nyour micropython device through `mpremote`\n\n```shell\nmpremote mip install github:pulkin/unbd\n```\n\nTo use `unbd` with cpython and/or in command-line\nenvironment use `pip`\n\n```shell\npip install git+https://github.com/pulkin/unbd\n```\n\nHow to use\n----------\n\nFirst, install `nbd` server on your host computer: it will\nserve file system images over your local network.\nThen, use the `snapmount` script on the host or the `unbd`\nmodule on the micropython device directly.\n\n- using `snapmount`\n\n  1. Install cpython package on your host computer\n     ```bash\n     pip install git+https://github.com/pulkin/unbd\n     ```\n  2. Connect your wifi-enabled micropython device to a serial port\n     on your host computer\n  3. Mount your source folder `src` with\n     ```bash\n     snapmount src\n     ```\n\n  Note that `snapmount` uses wifi to communicate host your\n  micropython device in station mode with the host computer.\n  It will attempt to deduce network credentials through\n  Network Manager on Linux (`nmcli`). You may explicitly supply\n  credentials through `--ssid` and `--passphrase`.\n\n- manually\n\n  1. Start NBD server on the host machine\n    \n     ```shell\n     nbd-server 33567 /full/path/to/fs.img -d\n     ```\n    \n  2. Connect and install `unbd` on your micropython device\n    \n     ```shell\n     mpremote mip install github:pulkin/unbd\n     ```\n    \n  3. Mount the remote device\n    \n     ```python\n     from unbd import connect\n     import os\n     os.mount(connect('host-ip-address', 33567, open=True), \"/mount\")\n     ```\n\n  Note that `fs.img` located on the host machine contains FAT image.\n\nKey features\n------------\n\n- fully virtual file system over wifi\n- relatively high performance\n- minimal setup needed\n- tiny footprint\n- no flash storage used (and no performance degradation\n  for intensive IO)\n\nPerformance\n-----------\n\nThe mounted filesystem speeds range from several Kbps up to\n100 Kbps in read and write. The final throughput is roughly the\nratio `block_size / network_latency`. Thus, to achieve maximal\nperformance:\n\n- increase `block_size` (4096 is about the saturated maximum)\n- ensure the wireless connection is stable\n\nFAT filesystem is, in general, twice as fast as `littlefs` for\nreading large files.\n\n### Real-world benchmarks\n\n| Case                              | LittleFS 512 | FAT 512 | FAT 4096 |\n|-----------------------------------|--------------|---------|----------|\n| App: ~100Kb, tens of source files | 33s          | 12s     | 9s       | \n\nExamples\n--------\n\n### `unbd`\n\nSimply mount the partition with default values (micropython)\n\n```python\nfrom unbd import connect\nos.mount(connect(host, port, open=True), \"/mount\")\n```\n\nMount `littlefs` with a large block size\n\n```python\nos.mount(os.VfsLfs2(connect(host, port, block_size=4096), readsize=4096), \"/mount\")\n```\n\nMount FAT with a large block size\n\n```python\nos.mount(os.VfsFat(connect(host, port, block_size=4096)), \"/mount\")\n```\n\n### Develop and test with `snapmount`\n\nSee also [bare-metal tests for this package](test/test_mp_esp32.py).\n\nRunning a test script `test.py` from `src`\n\n```python\nfrom snapmount import mounted\n\nwith mounted('src', endpoint=\"/\", **kwargs) as board:\n    out, err = board.exec_raw(\"import test\")\n    assert len(err) == 0\n```\n\nSame with `snapmount` in command line\n\n```bash\nsnapmount src --ssid=\"ssid\" --passphrase=\"secret\" --endpoint=/ --payload=\"import test\"\n```\n\nMore options\n\n```bash\nsnapmount src --verbose \\\n  --ssid=\"ssid\" \\\n  --passphrase=\"secret\" \\\n  --soft-reset \\ \n  --endpoint=/ \\\n  --fs=fat \\\n  --block-size=4096 \\\n  --payload=\"import test\"\n```\n\nLicense\n-------\n\n[LICENSE.md](LICENSE.md)\n","funding_links":[],"categories":["Libraries"],"sub_categories":["Communications"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpulkin%2Funbd","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpulkin%2Funbd","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpulkin%2Funbd/lists"}