{"id":22706703,"url":"https://github.com/mbari-org/lcm-websocket-server","last_synced_at":"2026-03-27T05:14:54.481Z","repository":{"id":197067933,"uuid":"619868690","full_name":"mbari-org/lcm-websocket-server","owner":"mbari-org","description":"WebSocket server for republishing LCM messages.","archived":false,"fork":false,"pushed_at":"2025-04-11T20:43:56.000Z","size":94,"stargazers_count":3,"open_issues_count":6,"forks_count":0,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-04-13T12:12:51.559Z","etag":null,"topics":["lcm","middleware","websocket"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mbari-org.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"2023-03-27T15:16:47.000Z","updated_at":"2025-04-11T20:43:08.000Z","dependencies_parsed_at":null,"dependency_job_id":"16e64e8b-8dbd-4afb-a9ef-e2a77f47d513","html_url":"https://github.com/mbari-org/lcm-websocket-server","commit_stats":null,"previous_names":["mbari-org/lcm-websocket-server"],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mbari-org%2Flcm-websocket-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mbari-org%2Flcm-websocket-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mbari-org%2Flcm-websocket-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mbari-org%2Flcm-websocket-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mbari-org","download_url":"https://codeload.github.com/mbari-org/lcm-websocket-server/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248710448,"owners_count":21149191,"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":["lcm","middleware","websocket"],"created_at":"2024-12-10T10:09:28.320Z","updated_at":"2026-03-27T05:14:54.429Z","avatar_url":"https://github.com/mbari-org.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 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\u003e [!TIP]\n\u003e 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. \n\n\u003e [!NOTE]\n\u003e 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### Dial Proxy\n\nThe `lcm-websocket-dial-proxy` command is a version of the JSON proxy 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\n**This command requires the `image` extension to be installed.** This can be done with:\n```bash\npip install lcm-websocket-server[image]\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\nThe Dial proxy depends on the `molars-lcmtypes` Python package to be installed. This package is not available on PyPI, so it must be built and installed manually; see the [MolaRS repository](https://github.com/CoMPASLab/molars/) for more info. \n\nThe `Dockerfile.dial` file can be used to build the image with the `molars-lcmtypes` package installed. For this, the Python wheel `molars_lcmtypes-0.0.0-py3-none-any.whl` must be placed at the repository root before building the image.\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","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmbari-org%2Flcm-websocket-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmbari-org%2Flcm-websocket-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmbari-org%2Flcm-websocket-server/lists"}