View Source README
Rclex
Rclex is a ROS 2 client library for Elixir.
This library lets you perform basic ROS 2 behaviors by calling out from Elixir code into the RCL (ROS Client Library) API, which uses the ROS 2 common hierarchy.
Additionally, publisher-subscriber (PubSub) communication between nodes and associated callback functions are executed by tasks, which are part of a lightweight process model. This enables generation of and communication between a large number of fault-tolerant nodes while suppressing memory load.
what-is-ros-2
What is ROS 2
ROS (Robot Operating System) is a next-generation Robot development platform. In both ROS and ROS 2, each functional unit is exposed as a node, and by combining these nodes you can create different robot applications. Additionally, communication between nodes uses a PubSub model where publisher and subscriber exchange information by specifying a common topic name.
The biggest difference between ROS and ROS 2 is that the DDS (Data Distribution Service) protocol was adopted for communication, and the library was divided in a hierarchical structure, allowing for the creation of ROS 2 client libraries in various languages. This has allowed for the creation of a robot application library in Elixir.
For details on ROS 2, see the official ROS 2 documentation.
recommended-environment
Recommended environment
Currently, we use the following environment as the main development target:
- Ubuntu 20.04.2 LTS (Focal Fossa)
- ROS 2 Foxy Fitzroy
- Elixir 1.13.4-otp-25
- Erlang/OTP 25.0.3
For other environments used to check the operation of this library, please refer to here.
The pre-built Docker images are available at Docker Hub. You can also try the power of Rclex with it easily. Please check "Docker Environment" section for details.
rclex
can be operated onto Nerves. Please refer to b5g-ex/rclex_on_nerves for more details!
features
Features
Currently, the Rclex API allows for the following:
- The ability to create a large number of publishers sending to the same topic.
- The ability to create large numbers of each combination of publishers, topics, and subscribers.
Documentation can be generated with ExDoc
and published on HexDocs.
You can find the docs at https://hexdocs.pm/rclex.
Please refer rclex/rclex_examples for the examples of usage along with the sample code.
how-to-use
How to use
This section explains the quickstart for rclex
onto the environment where ROS 2 and Elixir have been prepared.
create-the-project
Create the project
First of all, create the Mix project as a normal Elixir project.
mix new rclex_usage
install-rclex
Install rclex
rclex
is available in Hex.
You can install this package into your project
by adding rclex
to your list of dependencies in mix.exs
:
def deps do
[
{:rclex, "~> 0.8.0"}
]
end
After that, execute mix deps.get
into the project repository.
cd rclex_usage
mix deps.get
prepare-message-types
Prepare message types
Rclex provides pub/sub based topic communication using the message type defined in ROS 2. Please refer here for more details about message types in ROS 2.
Here, we show how to prepare the message type for topic communication, using the String
type as an example. First, write the following in config/config.exs
.
import Config
config :rclex, ros2_message_types: ["std_msgs/msg/String"]
Setup the environment for ROS 2.
source /opt/ros/foxy/setup.bash
Then, execute the following Mix task to generate required definitions and files for using message types.
mix rclex.gen.msgs
Now, you can acquire the environment for Rclex! You can operate Rclex API onto IEx.
implementation-and-execution-of-project
Implementation and execution of project
Here is the simplest example lib/rclex_usage.ex
that will publish the string to /chatter
topic.
defmodule RclexUsage do
def publish_message do
context = Rclex.rclexinit()
{:ok, node} = Rclex.ResourceServer.create_node(context, 'talker')
{:ok, publisher} = Rclex.Node.create_publisher(node, 'StdMsgs.Msg.String', 'chatter')
msg = Rclex.Msg.initialize('StdMsgs.Msg.String')
data = "Hello World from Rclex!"
msg_struct = %Rclex.StdMsgs.Msg.String{data: String.to_charlist(data)}
Rclex.Msg.set(msg, msg_struct, 'StdMsgs.Msg.String')
IO.puts("Rclex: Publishing: #{data}")
Rclex.Publisher.publish([publisher], [msg])
Rclex.Node.finish_job(publisher)
Rclex.ResourceServer.finish_node(node)
Rclex.shutdown(context)
end
end
Copy and paste the above code to lib/rclex_usage.ex
, and execute IEx.
iex -S mix
Operate the following on IEx.
iex()> RclexUsage.publish_message
00:04:40.701 [debug] JobExecutor start
00:04:40.705 [debug] talker0/chatter/pub
Rclex: Publishing: Hello World from Rclex!
00:04:40.706 [debug] publish ok
00:04:40.706 [debug] publisher finished: talker0/chatter/pub
00:04:40.710 [debug] finish node: talker0
{:ok, #Reference<0.2970499651.1284374532.3555>}
You can confirm the above operation by subscribing with ros2 topic echo
.
$ source /opt/ros/foxy/setup.bash
$ ros2 topic echo /chatter std_msgs/msg/String
data: Hello World from Rclex!
---
enhance-devepoment-experience
Enhance devepoment experience
This section describes the information mainly for developers.
docker-environment
Docker environment
This repository provides a docker compose
environment for library development with Docker.
As mentioned above, pre-built Docker images are available at Docker Hub, which can be used to easily try out Rclex.
You can set the environment variable $RCLEX_DOCKER_TAG
to the version of the target environment. Please refer to here for the available environments.
# optional: set to the target environment (default `latest`)
export RCLEX_DOCKER_TAG=latest
# create and start the container
docker compose up -d
# execute the container (with the workdir where this repository is mounted)
docker compose exec -w /root/rclex rclex_docker /bin/bash
# stop the container
docker compose down
automatic-execution-of-mix-test-etc
Automatic execution of mix test, etc.
mix test.watch
is introduced to automatically run unit test mix test
and code formatting mix format
every time the source code was editted.
$ mix test.watch
# or, run on docker by following
$ docker compose run --rm -w /root/rclex rclex_docker mix test.watch
confirmation-of-operation
Confirmation of operation
To check the operation of this library, we prepare rclex/rclex_connection_tests to test the communication with the nodes implemented with Rclcpp.
cd /path/to/yours
git clone https://github.com/rclex/rclex
git clone https://github.com/rclex/rclex_connection_tests
cd /path/to/yours/rclex_connection_tests
./run-all.sh
In GitHub Actions, we perform CI on multiple environments at Pull Requests. HOwever, we cannot guarantee operation in all of these environments.