Renaming packages to better align with REP-0144 guidelines

Author: openvmp

CMakeLists.txt

@@ -1,5 +1,5 @@
 cmake_minimum_required(VERSION 3.10)
-project(ros2_serial)
+project(remote_serial)
 
 # Compiler settings
 if(NOT CMAKE_CXX_STANDARD)
@@ -9,6 +9,7 @@ endif()
 if(CMAKE_COMPILER_IS_GNUCXX OR CMAKE_CXX_COMPILER_ID MATCHES "Clang")
   add_compile_options(-Wall -Wextra -Wpedantic)
 endif()
+add_compile_options(-fPIC)
 
 # Dependencies
 find_package(ament_cmake REQUIRED)

README.md

@@ -1,36 +1,79 @@
-# OpenVMP
+# remote_serial
 
-[![License](./license.svg)](./LICENSE.txt)
+[![License](./apache20.svg)](./LICENSE.txt)
 
-This package is a part of [the OpenVMP project](https://github.com/openvmp/openvmp).
-But it's designed to be universal and usable independently from the rest of OpenVMP or in a combination with select OpenVMP packages.
+This is an ultimate implementation of serial line interface for ROS2.
 
-## ROS2 serial driver
-
-This is an ultimate C++ implementation of serial port driver for ROS2.
-
-It can be used either as a library or a standalone process. In both cases it
-provides ROS2 interfaces for inter-process access, introspection and
+It provides ROS2 interfaces for inter-process access, introspection and
 debugging.
 It performs wisely in case of serial line saturation in any of
 the I/O directions, minimizing data loses and blocking behavior,
-ensuring maximum performance.
+ensuring optimum performance.
+
+This package implements a generic purpose serial port driver using
+character device files.
+However this package also implements most of the logic required for other
+serial line drivers (see the "Examples" section below).
+
+## ROS2 interfaces
+
+### Parameters
+
+All classes:
+
+- `serial_prefix`: the prefix to ROS2 interfaces exposed by this driver
+  ("/serial/<node-name>" by default)
+
+The factory class:
 
+- `serial_is_remote`: instructs whether
+  to instantiate the driver locally or to connect to a remote instance
+  ("true" by default)
 
-### Basic setup
+Serial port driver:
+
+- `serial_dev_name`: the character device path ("/dev/ttyS0" by default)
+- serial port settings:
+  - `serial_skip_init`: skip the port initialization (ignore the below parameters)
+  - `serial_baud_rate`: baud rate ("115200" by default)
+  - `serial_data`: data bits ("8" by default)
+  - `serial_parity`: parity bit ("false" by default)
+  - `serial_stop`: stop bits ("1" by default)
+  - `serial_flow_control`: hardware flow control ("false" by default)
+  - `serial_sw_flow_control`: software flow control ("false" by default)
+  - `serial_bs`: the size of read buffer ("1024" by default)
+
+### Topics
+
+#### Subscribers
+
+- `<namespace>/<serial_prefix>/inject/input`: injects the given bytes into
+  the serial line as if it was written to the line by the driver
+- `<namespace>/<serial_prefix>/inject/output`: injects the given bytes into
+  the serial line as if it was received by the driver from the line
+
+#### Publishers
+
+- `<namespace>/<serial_prefix>/inspect/input`: publishes data
+  received by the driver from the line
+- `<namespace>/<serial_prefix>/inspect/output`: publishes data
+  sent by the driver to the line
+
+## Basic setup
 
 Launch it as a separate node for each serial port:
 
 ```
-$ ros2 run ros2_serial ros2_serial_standalone
+$ ros2 run remote_serial remote_serial_standalone
 ```
 
 or
 
 ```
-$ ros2 run ros2_serial ros2_serial_standalone \
+$ ros2 run remote_serial remote_serial_standalone \
   --ros-args \
   --remap serial:__node:=serial_com1 \
+  -p serial_is_remote:=false \
   -p serial_prefix:=/serial/com1 \
   -p serial_dev_name:=/dev/ttyS0 \
   -p serial_baud_rate:=115200 \
@@ -42,15 +85,15 @@ $ ros2 run ros2_serial ros2_serial_standalone \
 
 ```mermaid
 flowchart TB
-    cli["$ ros2 topic echo /serial/com1"] -. "DDS" .-> topic_serial[/ROS2 interfaces:\n/serial/com1/.../]
+    cli["<p style='text-align:left'>$ ros2 topic echo /serial/com1/inspect/input\n$ ros2 topic echo /serial/com1/inspect/output\n$ ros2 topic pub /serial/com1/inject/output \\n&nbsp;&nbsp;&nbsp;std_msgs/msg/UInt8MultiArray {'data':'ATH+CHUP\r\ n'}</p>"] -. "DDS" .-> topic_serial[/ROS2 interfaces:\n/serial/com1/.../]
     app["Your process"] -- "DDS\n(with context switch)" --> topic_serial
-    subgraph serial["Process: ros2_serial_standalone"]
+    subgraph serial["Process: remote_serial_standalone"]
       topic_serial --> driver["Serial port driver"]
     end
     driver --> file{{"Character device: /dev/ttyS0"}}
 ```
 
-### Advanced setup
+## Advanced setup
 
 The more advanced setup is to initialize it as a separate node in the very executable which will be communicating with the port all the time
 (e.g. a MODBUS RTU implementation).
@@ -61,9 +104,9 @@ See an example of such a setup in the Modbus RTU package:
 
 ```mermaid
 flowchart TB
-    cli_serial["# Serial debugging\n$ ros2 topic echo /serial"] -. "DDS" ..-> topic_serial[/ROS2 interfaces:\n/serial/.../]
+    cli_serial["<p style='text-align:left'># Serial debugging and troubleshooting\n$ ros2 topic echo /serial/inspect/input\n...</p>"] -. "DDS" ..-> topic_serial[/ROS2 interfaces:\n/serial/.../]
     subgraph modbus_exe["Your process"]
-      subgraph serial["Library: ros2_serial"]
+      subgraph serial["Library: remote_serial"]
         topic_serial --> driver["Serial port driver"]
       end
       code["Your code"] -- "DDS\n(potentially without\ncontext switch)" --> topic_serial
@@ -73,16 +116,18 @@ flowchart TB
 ```
 
 
-### Implementation details
+## Implementation details
+
+The following diagram shows the high level view on the internals of this package:
 
 ```mermaid
 flowchart TB
     owner["Native API"]
     external["ROS2 Interface API"]
 
-    subgraph node["ros2_serial::Node"]
+    subgraph node["remote_serial::Node"]
 
-      subgraph interface_ros2["ros2_serial::InterfaceRemote"]
+      subgraph interface_ros2["remote_serial::Interface"]
         subgraph topics["Topics: /serial"]
           published_input[//inspect/input/]
           published_output[//inspect/output/]
@@ -94,11 +139,11 @@ flowchart TB
         end
       end
 
-      subgraph worker["ros2_serial::Port"]
+      subgraph worker["remote_serial::Port"]
         output_queue["Output Queue"]
         thread["Worker thread\nrunning select()"]
 
-        subgraph interface_native["ros2_serial::Implementation"]
+        subgraph interface_native["remote_serial::Implementation"]
           subgraph register_input_cb["register_input_cb()"]
             input_cb["input_cb()"]
           end
@@ -133,3 +178,85 @@ flowchart TB
     thread -- "output" --> fd -- "output" --> file
 
 ```
+
+## Implementing serial line drivers
+
+The serial line drivers implement the base class provided by this package.
+For C++ drivers, that means that they use
+`remote_serial::Implementation` as a parent class.
+Its constructor requires an instance of `rclcpp::Node` to read the
+parameters from.
+
+<i>
+Note:
+There can be more than one instance of `remote_serial::Implementation`
+per node. However they will all be controlled by the same parameters.
+Though the default value of the parameter `serial_prefix` can be passed
+into each individual constructor which is sufficient for common use cases.
+</i>
+<br/>
+<br/>
+
+The following methods need to be implemented by each driver:
+
+```c++
+public:
+  // output writes bytes to the serial line
+  virtual void output(const std::string &) override;
+
+  // register_input_cb is used to set the callback function which
+  // is called every time data is received from the serial line
+  virtual void register_input_cb(void (*)(const std::string &msg,
+                                          void *user_data),
+                                 void *user_data) override;
+```
+
+The users can chose one of three ways to interact with child classes of `remote_serial::Implementation`:
+
+- Link with the driver directly to make native API calls:
+
+  ```c++
+  auto serial = \
+    std::make_shared<driver_package::DriverClass>(node, "/serial");
+  serial->output("ATH+CHUP\r\n");
+  ```
+
+  In this case the driver is running within the same process and it is
+  destroyed when the `serial` object is destroyed.
+
+- Link with `remote_serial` to make ROS2 interface (DDS) calls
+  (locally or over a network):
+
+  ```c++
+  auto serial = \
+    std::make_shared<remote_serial::RemoteInterface>(node, "/serial");
+  serial->output("ATH+CHUP\r\n");
+  ```
+
+  In this case the driver can be elsewhere within DDS' reach
+  (same process or another side of the globe).
+
+- Let the runtime make the choice between the above two options:
+
+  ```c++
+  auto serial = \
+    remote_serial::Factory::New(node, "/serial");
+  // or
+  auto serial = \
+    driver_package::Factory::New(node, "/serial");
+  ```
+
+  In this case the boolean value of the parameter `serial_is_remote`
+  determines whether the driver is instantiated locally or if a remote
+  interface is used to reach the driver instantiated elsewhere.
+  Please, note, the trivial class `driver_package::Factory`
+  (similar to `remote_serial::Factory`) has to be written
+  to support this use case.
+
+## Examples
+
+### remote_microcontroller
+
+See the UART implementation in
+[remote_microcontroller](https://github.com/openvmp/microcontroller)
+for an example of a driver that implements `remote_serial`.

license.svg apache20.svg

@@ -13,15 +13,15 @@
 #include <memory>
 
 #include "rclcpp/rclcpp.hpp"
-#include "ros2_serial/interface.hpp"
+#include "remote_serial/interface.hpp"
 
-namespace ros2_serial {
+namespace remote_serial {
 
 class Factory {
  public:
   static std::shared_ptr<Interface> New(rclcpp::Node *node);
 };
 
-}  // namespace ros2_serial
+}  // namespace remote_serial
 
 #endif  // OPENVMP_SERIAL_FACTORY_H

include/ros2_serial/factory.hpp include/remote_serial/factory.hpp

@@ -14,12 +14,12 @@
 #include <string>
 
 #include "rclcpp/rclcpp.hpp"
-#include "ros2_serial/interface.hpp"
+#include "remote_serial/interface.hpp"
 #include "std_msgs/msg/empty.hpp"
 #include "std_msgs/msg/u_int8_multi_array.hpp"
 #include "std_srvs/srv/empty.hpp"
 
-namespace ros2_serial {
+namespace remote_serial {
 
 class Implementation : public Interface {
  public:
@@ -55,6 +55,6 @@ class Implementation : public Interface {
   void inject_output_handler_(const std_msgs::msg::UInt8MultiArray::SharedPtr);
 };
 
-}  // namespace ros2_serial
+}  // namespace remote_serial
 
 #endif  // OPENVMP_SERIAL_IMPLEMENTATION_H

include/ros2_serial/implementation.hpp include/remote_serial/implementation.hpp

@@ -21,17 +21,18 @@
 #define SERIAL_TOPIC_INJECT_OUTPUT "/inject/output"
 #define SERIAL_SERVICE_FLUSH "/flush"
 
-namespace ros2_serial {
+namespace remote_serial {
 
 class Interface {
  public:
   Interface(rclcpp::Node *node, const std::string &default_prefix = "");
   virtual ~Interface() {}
 
+  // output writes bytes to the serial line
   virtual void output(const std::string &) = 0;
 
-  // having pure pointers would improve performance here
-  // but it would be against the religion of so many
+  // register_input_cb is used to set the callback function which
+  // is called every time data is received from the serial line
   virtual void register_input_cb(void (*)(const std::string &msg,
                                           void *user_data),
                                  void *user_data) = 0;
@@ -47,6 +48,6 @@ class Interface {
   rclcpp::Parameter interface_prefix_;
 };
 
-}  // namespace ros2_serial
+}  // namespace remote_serial
 
 #endif  // OPENVMP_SERIAL_INTERFACE_H

include/ros2_serial/interface.hpp include/remote_serial/interface.hpp

@@ -16,12 +16,12 @@
 
 #include "rclcpp/callback_group.hpp"
 #include "rclcpp/rclcpp.hpp"
-#include "ros2_serial/interface.hpp"
+#include "remote_serial/interface.hpp"
 #include "std_msgs/msg/empty.hpp"
 #include "std_msgs/msg/u_int8_multi_array.hpp"
 #include "std_srvs/srv/empty.hpp"
 
-namespace ros2_serial {
+namespace remote_serial {
 
 class RemoteInterface final : public Interface {
  public:
@@ -55,6 +55,6 @@ class RemoteInterface final : public Interface {
   rclcpp::Client<std_srvs::srv::Empty>::SharedPtr clnt_flush_;
 };
 
-}  // namespace ros2_serial
+}  // namespace remote_serial
 
 #endif  // OPENVMP_SERIAL_INTERFACE_REMOTE_H

include/ros2_serial/interface_remote.hpp include/remote_serial/interface_remote.hpp

@@ -14,9 +14,9 @@
 #include <string>
 
 #include "rclcpp/rclcpp.hpp"
-#include "ros2_serial/port.hpp"
+#include "remote_serial/port.hpp"
 
-namespace ros2_serial {
+namespace remote_serial {
 
 class Node : public rclcpp::Node {
  public:
@@ -26,6 +26,6 @@ class Node : public rclcpp::Node {
   std::shared_ptr<Port> impl_;
 };
 
-}  // namespace ros2_serial
+}  // namespace remote_serial
 
 #endif  // OPENVMP_SERIAL_NODE_H

include/ros2_serial/node.hpp include/remote_serial/node.hpp

@@ -14,9 +14,9 @@
 #include <string>
 
 #include "rclcpp/rclcpp.hpp"
-#include "ros2_serial/implementation.hpp"
+#include "remote_serial/implementation.hpp"
 
-namespace ros2_serial {
+namespace remote_serial {
 
 class PortSettings {
  public:
@@ -61,6 +61,6 @@ class Port final : public Implementation {
   std::shared_ptr<Worker> worker_;
 };
 
-}  // namespace ros2_serial
+}  // namespace remote_serial
 
 #endif  // OPENVMP_SERIAL_PORT_H