{"id":28061302,"url":"https://github.com/rclex/rclex","last_synced_at":"2025-05-12T09:57:10.449Z","repository":{"id":39710398,"uuid":"225644990","full_name":"rclex/rclex","owner":"rclex","description":"Rclex: ROS 2 Client Library for Elixir","archived":false,"fork":false,"pushed_at":"2025-03-06T23:48:12.000Z","size":9325,"stargazers_count":141,"open_issues_count":20,"forks_count":13,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-03-07T00:27:12.847Z","etag":null,"topics":["elixir","iot","pubsub","ros","ros2"],"latest_commit_sha":null,"homepage":"https://hexdocs.pm/rclex","language":"Elixir","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rclex.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","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}},"created_at":"2019-12-03T14:51:13.000Z","updated_at":"2025-03-06T14:45:28.000Z","dependencies_parsed_at":"2023-10-12T07:06:23.905Z","dependency_job_id":"0efbc4dc-9032-436d-9475-e2d8a6c1b950","html_url":"https://github.com/rclex/rclex","commit_stats":{"total_commits":666,"total_committers":15,"mean_commits":44.4,"dds":0.7402402402402403,"last_synced_commit":"2bb83db7ddd28f67ff388bd6a504a240e369c627"},"previous_names":[],"tags_count":34,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rclex%2Frclex","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rclex%2Frclex/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rclex%2Frclex/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rclex%2Frclex/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rclex","download_url":"https://codeload.github.com/rclex/rclex/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253712613,"owners_count":21951779,"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":["elixir","iot","pubsub","ros","ros2"],"created_at":"2025-05-12T09:57:07.347Z","updated_at":"2025-05-12T09:57:10.437Z","avatar_url":"https://github.com/rclex.png","language":"Elixir","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Hex version](https://img.shields.io/hexpm/v/rclex.svg \"Hex version\")](https://hex.pm/packages/rclex)\n[![API docs](https://img.shields.io/hexpm/v/rclex.svg?label=hexdocs \"API docs\")](https://hexdocs.pm/rclex/readme.html)\n[![License](https://img.shields.io/hexpm/l/rclex.svg)](https://github.com/rclex/rclex/blob/main/LICENSE)\n[![ci-latest](https://github.com/rclex/rclex/actions/workflows/ci-latest.yml/badge.svg)](https://github.com/rclex/rclex/actions/workflows/ci-latest.yml)\n[![ci-all_version](https://github.com/rclex/rclex/actions/workflows/ci-all_version.yml/badge.svg)](https://github.com/rclex/rclex/actions/workflows/ci-all_version.yml)\n\n[日本語のREADME](README_ja.md)\n\n# Rclex\n\nRclex is a ROS 2 client library for the functional language [Elixir](https://elixir-lang.org/).\n\nThis library lets you perform basic ROS 2 behaviors by calling out from Elixir code into the RCL (ROS Client Library) API, which\nuses the ROS 2 common hierarchy.\n\nAdditionally, publisher-subscriber (PubSub) communication between nodes and associated callback functions are executed as Erlang lightweight processes.\nThis enables the creation of and communication between a large number of fault-tolerant\nnodes while suppressing memory load.\n\n## What is ROS 2\n\nROS 2 (Robot Operating System 2) is a state-of-the-art Robot development platform. In ROS 2, each functional\nunit is exposed as a node, and by combining these nodes you can create different robot applications. Additionally,\ncommunication between nodes uses a PubSub model where publishers and subscribers exchange information by specifying a\ncommon topic name.\n\nThe main benefits of ROS 2 are that the DDS (Data Distribution Service) protocol was adopted for\ncommunication, and the library was divided into a hierarchical structure.\nThis allows us to develop  ROS 2 client libraries in various languages and, of course, to build robot applications in Elixir.\n\nFor details on ROS 2, see [the official ROS 2 Documentation](https://docs.ros.org/en/rolling/index.html).\n\n## Recommended environment\n\n### Native environment\n\nThe basic and recommended environment is where the host (development) and the target (operation) are the same.\n\nCurrently, we use the following environment as the main development target:\n\n- Ubuntu 22.04 LTS (Jammy Jellyfish)\n- ROS 2 Humble Hawksbill\n- Elixir 1.17.3-otp-27\n- Erlang/OTP 27.2.4\n\nWe highly recommend using [Humble Hawksbill](https://docs.ros.org/en/rolling/Releases/Release-Humble-Hawksbill.html) for ROS 2 LTS distribution.\nWe also confirmed the operation of this library with [Jazzy Jalisco](https://docs.ros.org/en/rolling/Releases/Release-Jazzy-Jalisco.html) on Ubuntu 24.04 LTS. See details in [PR#361](https://github.com/rclex/rclex/pull/361).\n\nWe do not support ROS 2 Distributions that have already reached EOL in the development of the latest version.\nThe last supported releases are as follows.\n\n- Foxy Fitzroy: [v0.11.3](https://github.com/rclex/rclex/releases/tag/v0.11.3)\n- Galactic Geochelone: [v0.11.3](https://github.com/rclex/rclex/releases/tag/v0.11.3)\n- Iron Irwini: [v0.11.3](https://github.com/rclex/rclex/releases/tag/v0.11.3)\n\nFor other environments used to check the operation of this library, please refer to [here](https://github.com/rclex/rclex_docker#available-versions-docker-tags).\n\n### Docker environment\n\nThe pre-built Docker images are available at [Docker Hub](https://hub.docker.com/r/rclex/rclex_docker).\nYou can also try the power of Rclex with it easily. Please check [\"Docker Environment\"](#Docker-environment) section for details.\n\n### Nerves device (target)\n\n`rclex` can be operated onto Nerves. In this case, you do not need to prepare the ROS 2 environment on the host computer to build Nerves project (so awesome!).\n\nPlease refer to [Use on Nerves](USE_ON_NERVES.md) section and [b5g-ex/rclex_on_nerves](https://github.com/b5g-ex/rclex_on_nerves) example repository for more details!\n\n## Features\n\nCurrently, the Rclex API allows for the following:\n\n1. The ability to create a large number of publishers sending to the same topic.\n2. The ability to create large numbers of each combination of publishers, topics, and subscribers.\n\nYou can find the API documentation at [https://hexdocs.pm/rclex](https://hexdocs.pm/rclex).\n\nPlease refer [rclex/rclex_examples](https://github.com/rclex/rclex_examples) for the examples of usage along with the sample code.\n\n## How to use\n\nThis section explains the quickstart for `rclex` in the native environment where ROS 2 and Elixir have been installed.\n\n### Create the project\n\nFirst of all, create the Mix project as a normal Elixir project.\n\n```\nmix new rclex_usage\ncd rclex_usage\n```\n\n### Install rclex\n\n`rclex` is [available in Hex](https://hex.pm/docs/publish).\n\nYou can install this package into your project\nby adding `rclex` to your list of dependencies in `mix.exs`:\n\n```elixir\n  defp deps do\n    [\n      ...\n      {:rclex, \"~\u003e 0.12.0\"},\n      ...\n    ]\n  end\n```\n\nAfter that, execute `mix deps.get` into the project repository.\n\n```\nmix deps.get\n```\n\n### Setup the ROS 2 environment\n\n```\nsource /opt/ros/humble/setup.bash\n```\n\n## Configure ROS 2 message types you want to use\n\nRclex provides pub/sub-based topic communication using the message type defined in ROS 2. Please refer [here](https://docs.ros.org/en/humble/Concepts/About-ROS-Interfaces.html) for more details about message types in ROS 2.\n\nThe message types you want to use in your project can be specified in `ros2_message_types` in `config/config.exs`. \nMultiple message types can be specified separated by comma `,`.\n\nThe following `config/config.exs` example wants to use `String` type.\n\n```elixir\nimport Config\n\nconfig :rclex, ros2_message_types: [\"std_msgs/msg/String\"]\n```\n\nThen, execute the following Mix task to generate required definitions and files for message types.\n\n```\nmix rclex.gen.msgs\n```\n\nWhen editing `config/config.exs` to change the message types, do `mix rclex.gen.msgs` again.\n\n### Write Rclex code\n\nNow, you can acquire the environment for [Rclex API](https://hexdocs.pm/rclex/api-reference.html)! Of course, you can execute APIs on IEx directly.\n\nHere is the simplest implementation example `lib/rclex_usage.ex` that will publish the string to `/chatter` topic.\n\n```elixir\ndefmodule RclexUsage do\n  alias Rclex.Pkgs.StdMsgs\n\n  def publish_message do\n    Rclex.start_node(\"talker\")\n    Rclex.start_publisher(StdMsgs.Msg.String, \"/chatter\", \"talker\")\n\n    data = \"Hello World from Rclex!\"\n    msg = struct(StdMsgs.Msg.String, %{data: data})\n\n    IO.puts(\"Rclex: Publishing: #{data}\")\n    Rclex.publish(msg, \"/chatter\", \"talker\")\n  end\nend\n```\n\nPlease also check the examples for Rclex.\n\n- [rclex/rclex_examples](https://github.com/rclex/rclex_examples)\n\n### Build and Execute\n\nBuild your application as follows.\n\n```\nmix compile\niex -S mix\n```\n\nOperate the following command on IEx.\n\n```\niex()\u003e RclexUsage.publish_message\nRclex: Publishing: Hello World from Rclex!\n:ok\n```\n\nYou can confirm the above operation by subscribing with `ros2 topic echo` from the other terminal.\n\n```\n$ source /opt/ros/humble/setup.bash\n$ ros2 topic echo /chatter std_msgs/msg/String\ndata: Hello World from Rclex!\n---\n```\n\n## Enhance devepoment experience\n\nThis section describes the information mainly for developers.\n\n### Docker environment\n\nThis repository provides a `docker compose` environment for library development with Docker.\n\nAs mentioned above, pre-built Docker images are available at [Docker Hub](https://hub.docker.com/r/rclex/rclex_docker), which can be used to easily try out Rclex.\nYou can set the environment variable `$RCLEX_DOCKER_TAG` to the version of the target environment. Please refer to [here](https://github.com/rclex/rclex_docker#available-versions-docker-tags) for the available environments.\n\n```\n# optional: set to the target environment (default `latest`)\nexport RCLEX_DOCKER_TAG=latest\n# create and start the container\ndocker compose up -d\n# execute the container (with the workdir where this repository is mounted)\ndocker compose exec -w /root/rclex rclex_docker /bin/bash\n# stop the container\ndocker compose down\n```\n\nIn [GitHub Actions](https://github.com/rclex/rclex/actions), we perform CI on multiple tool versions at Pull Requests by using these Docker environments. However, we cannot guarantee operation in all of these environments.\n\n### Automatic execution of mix test, etc.\n\n`mix test.watch` is introduced to automatically run unit test `mix test` and code formatting `mix format` every time the source code was edited.\n\n```\n$ mix test.watch\n# or, run on docker by following\n$ docker compose run --rm -w /root/rclex rclex_docker mix test.watch\n```\n\n### Confirmation of communication operation\n\nTo check the operation, especially for communication features of this library, we prepare [rclex/rclex_connection_tests](https://github.com/rclex/rclex_connection_tests) to test the communication with the nodes implemented with Rclcpp.\n\n```\ncd /path/to/yours\ngit clone https://github.com/rclex/rclex\ngit clone https://github.com/rclex/rclex_connection_tests\ncd /path/to/yours/rclex_connection_tests\n./run-all.sh\n```\n\n## Presentations\n\n- Rclex on Nerves: a bare minimum runtime platform for ROS 2 nodes in Elixir\n  - [ROSCon 2023](https://roscon.ros.org/2023/)\n  - [Video](https://vimeo.com/879001529/b23eaacae8) | [SpeakerDeck](https://speakerdeck.com/takasehideki/rclex-on-nerves-a-bare-minimum-runtime-platform-for-ros-2-nodes-in-elixir)\n- On the way to achieve autonomous node communication in the Elixir ecosystem\n  - [Code BEAM America 2022](https://codebeamamerica.com/archives/CBA_2023/index.html) at 2022/11/03\n  - [Video](https://www.youtube.com/watch?v=Y4IASAU4Bjo) | [SpeakerDeck](https://speakerdeck.com/takasehideki/on-the-way-to-achieve-autonomous-node-communication-in-the-elixir-ecosystem)\n- Rclex: A Library for Robotics meet Elixir\n  - [Code BEAM America 2021](https://codesync.global/conferences/code-beam-sf-2021/) at 2021/11/05\n  - [Video](https://www.youtube.com/watch?v=9B5lQ3kQ_wI) | [SlideShare](https://www.slideshare.net/takasehideki/rclex-a-library-for-robotics-meet-elixir)\n\n## Maintainers and developers (including past)\n\n- [@takasehideki](https://github.com/takasehideki)\n- [@s-hosoai](https://github.com/s-hosoai)\n- [@pojiro](https://github.com/pojiro)\n- [@HiroiImanishi](https://github.com/HiroiImanishi)\n- [@kebus426](https://github.com/kebus426)\n- [@shiroro466](https://github.com/shiroro466)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frclex%2Frclex","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frclex%2Frclex","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frclex%2Frclex/lists"}