# Serial Diode
Generic wire protocol and implementation for one-way data transfer over UART serial.
## Usage
### General
The serial device can be specified with `--device` and baudrate with `--baudrate`.
If device is unspecified, it will attempt to guess the correct device based on platform and name.
If baudrate is unspecified, it defaults to 115200 Hz.
See `--help` for detailed usage information.
### Send
Run `diode send <path/to/file>` to send `<file>`.
### Receive
Run `diode listen`, which will listen forever. When it receives a valid payload, it will write it to `out/<file>` where `<file>` was specified in the payload metadata.
Note that on some systems this may need to be run as root to allow access to the serial port.
It is generally preferable to add the user to the appropriate group with something similar to `usermod -a -G uucp <username>`.
## Wire format
┌─────┬──────────┬─────────────┬──────┬─────┬───────┐
│ SOT │ metadata │ data_length │ data │ EXT │ crc32 │
└─────┴──────────┴─────────────┴──────┴─────┴───────┘
Here:
* `metadata` is 32 bytes,
* `data_length` is 8 bytes,
* `data` is `data_length` bytes,
* `crc32` is 8 bytes,
* `SOT` and `EXT` are the bytes `x02`, `x03`,
* `crc32` is the value of the CRC32 function acting on `metadata || data`.
## Installation
Install in developer mode with `make install_dev && source venv/bin/activate`.
Install as user with `make install`.
Install [from PyPI](https://pypi.org/project/data-diode/) with `pip install data-diode`.
Install Bash completion with `source bash_completion/diode`.
## Testing
Run `make test`.
For ad-hoc testing, `socat -d -d pty,raw,echo=0 pty,raw,echo=0` can be useful to connect two virtual serial devices.
If a physical serial device exists, connect with `screen /dev/<device_name> [<baud_rate>]` where `<baud_rate>` is likely 115200.
Raw data
{
"_id": null,
"home_page": "https://github.com/fionn/diode",
"name": "data-diode",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "",
"keywords": "diode,data diode",
"author": "Fionn Fitzmaurice",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/ec/a2/bf17ba687fe005aef8d950e1743f41840a74e064ad6d47d058c032b613ab/data-diode-0.0.4.tar.gz",
"platform": null,
"description": "# Serial Diode\n\nGeneric wire protocol and implementation for one-way data transfer over UART serial.\n\n## Usage\n\n### General\n\nThe serial device can be specified with `--device` and baudrate with `--baudrate`.\nIf device is unspecified, it will attempt to guess the correct device based on platform and name.\nIf baudrate is unspecified, it defaults to 115200 Hz.\n\nSee `--help` for detailed usage information.\n\n### Send\n\nRun `diode send <path/to/file>` to send `<file>`.\n\n### Receive\n\nRun `diode listen`, which will listen forever. When it receives a valid payload, it will write it to `out/<file>` where `<file>` was specified in the payload metadata.\n\nNote that on some systems this may need to be run as root to allow access to the serial port.\nIt is generally preferable to add the user to the appropriate group with something similar to `usermod -a -G uucp <username>`.\n\n## Wire format\n\n \u250c\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n \u2502 SOT \u2502 metadata \u2502 data_length \u2502 data \u2502 EXT \u2502 crc32 \u2502\n \u2514\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n\nHere:\n* `metadata` is 32 bytes,\n* `data_length` is 8 bytes,\n* `data` is `data_length` bytes,\n* `crc32` is 8 bytes,\n* `SOT` and `EXT` are the bytes `x02`, `x03`,\n* `crc32` is the value of the CRC32 function acting on `metadata || data`.\n\n## Installation\n\nInstall in developer mode with `make install_dev && source venv/bin/activate`.\n\nInstall as user with `make install`.\n\nInstall [from PyPI](https://pypi.org/project/data-diode/) with `pip install data-diode`.\n\nInstall Bash completion with `source bash_completion/diode`.\n\n## Testing\n\nRun `make test`.\n\nFor ad-hoc testing, `socat -d -d pty,raw,echo=0 pty,raw,echo=0` can be useful to connect two virtual serial devices.\nIf a physical serial device exists, connect with `screen /dev/<device_name> [<baud_rate>]` where `<baud_rate>` is likely 115200.\n",
"bugtrack_url": null,
"license": "",
"summary": "Send and receive data over serial diode",
"version": "0.0.4",
"project_urls": {
"Bug Tracker": "https://github.com/fionn/diode/issues",
"Changelog": "https://github.com/fionn/diode/tags",
"Documentation": "https://github.com/fionn/diode/blob/master/README.md",
"Download": "https://github.com/fionn/diode/archive/refs/heads/master.zip",
"Homepage": "https://github.com/fionn/diode",
"PyPI": "https://pypi.org/project/data-diode/",
"Source Code": "https://github.com/fionn/diode"
},
"split_keywords": [
"diode",
"data diode"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "6a4529795b34230328165cd15e495fe86bed9fc4c1030f53027ad5b6bd5b4dd0",
"md5": "adf48242397ebf3e2b2d84cb9bda19d9",
"sha256": "ccc281bdb8f9ba709d4bf329aa219c919f28f7a55de98a6708cdaffe8dc27cd2"
},
"downloads": -1,
"filename": "data_diode-0.0.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "adf48242397ebf3e2b2d84cb9bda19d9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 7163,
"upload_time": "2023-12-21T17:43:39",
"upload_time_iso_8601": "2023-12-21T17:43:39.454510Z",
"url": "https://files.pythonhosted.org/packages/6a/45/29795b34230328165cd15e495fe86bed9fc4c1030f53027ad5b6bd5b4dd0/data_diode-0.0.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "eca2bf17ba687fe005aef8d950e1743f41840a74e064ad6d47d058c032b613ab",
"md5": "62e8aaf646220f2ed3fe70285bc64d42",
"sha256": "bbd9bf4f6c8a41dbcf95b8ccfb39a9ceb145d32108157027bcbb2315c144b36f"
},
"downloads": -1,
"filename": "data-diode-0.0.4.tar.gz",
"has_sig": false,
"md5_digest": "62e8aaf646220f2ed3fe70285bc64d42",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 6444,
"upload_time": "2023-12-21T17:43:40",
"upload_time_iso_8601": "2023-12-21T17:43:40.648521Z",
"url": "https://files.pythonhosted.org/packages/ec/a2/bf17ba687fe005aef8d950e1743f41840a74e064ad6d47d058c032b613ab/data-diode-0.0.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-12-21 17:43:40",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "fionn",
"github_project": "diode",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "data-diode"
}
JSON
