| Name | lcm-websocket-server JSON |
| Version |
0.2.0
JSON |
| download |
| home_page | |
| Summary | WebSocket server for republishing LCM messages |
| upload_time | 2024-03-01 17:52:03 |
| maintainer | |
| docs_url | None |
| author | Kevin Barnard |
| requires_python | >=3.9,<4.0 |
| license | MIT |
| keywords |
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# lcm-websocket-server
WebSocket server for republishing LCM messages.
## :hammer: Installation
**You must have the LCM Python package installed before using `lcm-websocket-server`.** See the [LCM build instructions](http://lcm-proj.github.io/lcm/content/build-instructions.html) for more information.
### From PyPI
```bash
pip install lcm-websocket-server
```
### From source
```bash
poetry build
pip install dist/lcm_websocket_server-*-py3-none-any.whl
```
## :rocket: Usage
> [!TIP]
> The `lcm-websocket-server` commands have a log level of `ERROR` by default. To see more detailed logs, use the `-v` flag. Repeated use of the flag increases the verbosity from `ERROR` to `WARNING`, `INFO`, and `DEBUG`.
### JSON Proxy
The `lcm-websocket-json-proxy` command can be used to run a server that republishes LCM messages as JSON over a WebSocket connection. **This command requires the `image` extension to be installed.** This can be done with:
```bash
pip install lcm-websocket-server[image]
```
> [!NOTE]
> The `lcm-websocket-server` command has been renamed to `lcm-websocket-json-proxy`. The old name is still available for backwards compatibility, but it is recommended to use the new name.
To run the server locally on port 8765 and republish messages on all channels:
```bash
lcm-websocket-json-proxy --host localhost --port 8765 --channel '.*' your_lcm_types_packages
```
The `lcm_packages` argument is the name of the package (or comma-separated list of packages) that contains the LCM Python message definitions. Submodules are scanned recursively and registered so they can be automatically identified, decoded, and republished.
### Example: `compas_lcmtypes`
For example, the `compas_lcmtypes` package contains LCM types for the CoMPAS lab. These can be installed with:
```bash
pip install compas-lcmtypes==0.1.0
```
Then, the server can be run with:
```bash
lcm-websocket-server compas_lcmtypes
```
### JPEG Proxy
The `lcm-websocket-jpeg-proxy` command can be used to run a server that republishes CoMPAS `senlcm::image_t` LCM messages as JPEG images over a WebSocket connection. The images are decoded from a variety of pixel formats and encoded as JPEG resolution as a configurable resolution and quality.
See the [CoMPAS LCM types repository](https://bitbucket.org/compas-sw/compas_lcmtypes) for more information.
To run the server locally on port 8766 and republish images for the `CAMERA` channel at 75% quality at 1.0 scale:
```bash
lcm-websocket-jpeg-proxy --host localhost --port 8766 --quality 75 --scale 1.0 --channel CAMERA
```
### Dial Proxy
The `lcm-websocket-dial-proxy` command is a combined version of the JSON and JPEG proxies, tweaked for [Dial](https://github.com/mbari-org/dial). It can be used to run a server that republishes CoMPAS `senlcm::image_t` LCM messages as JPEG images and all other CoMPAS LCM messages as JSON over a WebSocket connection. All text frames sent over the WebSocket connection are encoded as JSON. Binary frames are JPEG images with a prepended header and channel name that conforms to the [LCM log file format](http://lcm-proj.github.io/lcm/content/log-file-format.html) with the following considerations:
- The *event number* is always 0. This is because the server is not reading from a log file, but rather republishing messages as they are received.
- The *timestamp* is the timestamp from the `image_t` event's contained `header_t` timestamp. The timestamp is conventionally in units of microseconds, but this is not guaranteed.
- The *data length* represents the original image data length, not the length of the JPEG image data.
Therefore, the binary frame is laid out as follows:
```
[28 byte LCM header] [channel name] [JPEG]
```
To run the server locally on port 8765 and republish messages on all channels (JPEG quality and scale are configured as before):
```bash
lcm-websocket-dial-proxy --host localhost --port 8765 --channel '.*' --quality 75 --scale 1.0
```
## :whale: Docker
### Build
A Docker image to run the `lcm-websocket-server` can be built with:
```bash
./scripts/docker_build.sh
```
This will create the `mbari/lcm-websocket-server` image.
### Run
The container can be run with:
```bash
docker run \
--name lcm-websocket-server \
--rm \
-e HOST=0.0.0.0 \
-e PORT=8765 \
-e CHANNEL=".*" \
-v /path/to/your_lcm_types_package:/app/your_lcm_types_package \
-e LCM_PACKAGES=your_lcm_types_package \
--network=host \
-d \
mbari/lcm-websocket-server
```
Note that the `HOST`, `PORT`, and `CHANNEL` environment variables specified above are the defaults for the `mbari/lcm-websocket-server` image. These can be omitted if the defaults are acceptable.
The `LCM_PACKAGES` environment variable should be set to the name of the package (or comma-separated list of packages) that contains the LCM Python message definitions. The `/app` directory is included in the `PYTHONPATH` so that any packages mounted there (as shown with `-v` above) can be imported.
It's recommended to run with `--network=host` to avoid issues with LCM over UDP. This will allow the container to use the host's network stack.
Raw data
{
"_id": null,
"home_page": "",
"name": "lcm-websocket-server",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.9,<4.0",
"maintainer_email": "",
"keywords": "",
"author": "Kevin Barnard",
"author_email": "kbarnard@mbari.org",
"download_url": "https://files.pythonhosted.org/packages/61/4b/166f8a49fccbe04f229822196026582d2f7b7c381335126211e19b4d954b/lcm_websocket_server-0.2.0.tar.gz",
"platform": null,
"description": "# lcm-websocket-server\n\nWebSocket server for republishing LCM messages.\n\n## :hammer: Installation\n\n**You must have the LCM Python package installed before using `lcm-websocket-server`.** See the [LCM build instructions](http://lcm-proj.github.io/lcm/content/build-instructions.html) for more information.\n\n### From PyPI\n\n```bash\npip install lcm-websocket-server\n```\n\n### From source\n\n```bash\npoetry build\npip install dist/lcm_websocket_server-*-py3-none-any.whl\n```\n\n## :rocket: Usage\n\n> [!TIP]\n> The `lcm-websocket-server` commands have a log level of `ERROR` by default. To see more detailed logs, use the `-v` flag. Repeated use of the flag increases the verbosity from `ERROR` to `WARNING`, `INFO`, and `DEBUG`.\n\n\n### JSON Proxy\n\nThe `lcm-websocket-json-proxy` command can be used to run a server that republishes LCM messages as JSON over a WebSocket connection. **This command requires the `image` extension to be installed.** This can be done with:\n```bash\npip install lcm-websocket-server[image]\n```\n\n> [!NOTE]\n> The `lcm-websocket-server` command has been renamed to `lcm-websocket-json-proxy`. The old name is still available for backwards compatibility, but it is recommended to use the new name.\n\nTo run the server locally on port 8765 and republish messages on all channels:\n```bash\nlcm-websocket-json-proxy --host localhost --port 8765 --channel '.*' your_lcm_types_packages\n```\n\nThe `lcm_packages` argument is the name of the package (or comma-separated list of packages) that contains the LCM Python message definitions. Submodules are scanned recursively and registered so they can be automatically identified, decoded, and republished. \n\n### Example: `compas_lcmtypes`\n\nFor example, the `compas_lcmtypes` package contains LCM types for the CoMPAS lab. These can be installed with:\n```bash\npip install compas-lcmtypes==0.1.0\n```\n\nThen, the server can be run with:\n```bash\nlcm-websocket-server compas_lcmtypes\n```\n\n### JPEG Proxy\n\nThe `lcm-websocket-jpeg-proxy` command can be used to run a server that republishes CoMPAS `senlcm::image_t` LCM messages as JPEG images over a WebSocket connection. The images are decoded from a variety of pixel formats and encoded as JPEG resolution as a configurable resolution and quality.\n\nSee the [CoMPAS LCM types repository](https://bitbucket.org/compas-sw/compas_lcmtypes) for more information.\n\nTo run the server locally on port 8766 and republish images for the `CAMERA` channel at 75% quality at 1.0 scale:\n```bash\nlcm-websocket-jpeg-proxy --host localhost --port 8766 --quality 75 --scale 1.0 --channel CAMERA\n```\n\n### Dial Proxy\n\nThe `lcm-websocket-dial-proxy` command is a combined version of the JSON and JPEG proxies, tweaked for [Dial](https://github.com/mbari-org/dial). It can be used to run a server that republishes CoMPAS `senlcm::image_t` LCM messages as JPEG images and all other CoMPAS LCM messages as JSON over a WebSocket connection. All text frames sent over the WebSocket connection are encoded as JSON. Binary frames are JPEG images with a prepended header and channel name that conforms to the [LCM log file format](http://lcm-proj.github.io/lcm/content/log-file-format.html) with the following considerations:\n- The *event number* is always 0. This is because the server is not reading from a log file, but rather republishing messages as they are received.\n- The *timestamp* is the timestamp from the `image_t` event's contained `header_t` timestamp. The timestamp is conventionally in units of microseconds, but this is not guaranteed.\n- The *data length* represents the original image data length, not the length of the JPEG image data.\n\nTherefore, the binary frame is laid out as follows:\n```\n[28 byte LCM header] [channel name] [JPEG]\n```\n\nTo run the server locally on port 8765 and republish messages on all channels (JPEG quality and scale are configured as before):\n```bash\nlcm-websocket-dial-proxy --host localhost --port 8765 --channel '.*' --quality 75 --scale 1.0\n```\n\n## :whale: Docker\n\n### Build\n\nA Docker image to run the `lcm-websocket-server` can be built with:\n\n```bash\n./scripts/docker_build.sh\n```\n\nThis will create the `mbari/lcm-websocket-server` image.\n\n### Run\n\nThe container can be run with:\n\n```bash\ndocker run \\\n --name lcm-websocket-server \\\n --rm \\\n -e HOST=0.0.0.0 \\\n -e PORT=8765 \\\n -e CHANNEL=\".*\" \\\n -v /path/to/your_lcm_types_package:/app/your_lcm_types_package \\\n -e LCM_PACKAGES=your_lcm_types_package \\\n --network=host \\\n -d \\\n mbari/lcm-websocket-server\n```\n\nNote that the `HOST`, `PORT`, and `CHANNEL` environment variables specified above are the defaults for the `mbari/lcm-websocket-server` image. These can be omitted if the defaults are acceptable.\n\nThe `LCM_PACKAGES` environment variable should be set to the name of the package (or comma-separated list of packages) that contains the LCM Python message definitions. The `/app` directory is included in the `PYTHONPATH` so that any packages mounted there (as shown with `-v` above) can be imported.\n\nIt's recommended to run with `--network=host` to avoid issues with LCM over UDP. This will allow the container to use the host's network stack.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "WebSocket server for republishing LCM messages",
"version": "0.2.0",
"project_urls": null,
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8d20ea414f315baa40de01c8c4e95d6ce4e39dfdcc88196b44ab225c5eb49624",
"md5": "9148c2a633020380620f64a62f59152b",
"sha256": "066572b4375f7183c7ee42b1782f4219e1c9acc43b01496868067e1e1f5a28d5"
},
"downloads": -1,
"filename": "lcm_websocket_server-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9148c2a633020380620f64a62f59152b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9,<4.0",
"size": 17124,
"upload_time": "2024-03-01T17:52:02",
"upload_time_iso_8601": "2024-03-01T17:52:02.735470Z",
"url": "https://files.pythonhosted.org/packages/8d/20/ea414f315baa40de01c8c4e95d6ce4e39dfdcc88196b44ab225c5eb49624/lcm_websocket_server-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "614b166f8a49fccbe04f229822196026582d2f7b7c381335126211e19b4d954b",
"md5": "332fe03495cf6e3adb9c34af83550f97",
"sha256": "f038f4c56e96025f310a01872e9795bdbe570e7eaee9f7d90848f3566b06d4fe"
},
"downloads": -1,
"filename": "lcm_websocket_server-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "332fe03495cf6e3adb9c34af83550f97",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9,<4.0",
"size": 13087,
"upload_time": "2024-03-01T17:52:03",
"upload_time_iso_8601": "2024-03-01T17:52:03.908946Z",
"url": "https://files.pythonhosted.org/packages/61/4b/166f8a49fccbe04f229822196026582d2f7b7c381335126211e19b4d954b/lcm_websocket_server-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-01 17:52:03",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "lcm-websocket-server"
}
