{
  "id": "pulkin/unbd",
  "name": "unbd",
  "prettyName": "unbd",
  "description": "Micro implementation of network block device (NBD) for micropython",
  "version": "",
  "author": "pulkin",
  "license": "BSD-2-Clause",
  "tags": [],
  "status": "VALID",
  "official": false,
  "source": "https://github.com/pulkin/unbd",
  "updatedAt": "2025-06-28T07:01:30.491Z",
  "page": "https://checkmim.com/packages/pulkin+unbd",
  "createdAt": "2025-05-27T04:28:22.338Z",
  "submittedBy": "oliverr",
  "install": {
    "mpremote": "mpremote mip install github:pulkin/unbd",
    "mip": "import mip; mip.install(\"github:pulkin/unbd\")"
  },
  "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"
}