Allow custom transports (#21)

* Allow custom transports

Signed-off-by: Pablo Garrido <pablogs9@gmail.com>

* Indentatation

Signed-off-by: Pablo Garrido <pablogs9@gmail.com>

* Docs

Signed-off-by: Pablo Garrido <pablogs9@gmail.com>

* Update macros

Signed-off-by: Pablo Garrido <pablogs9@gmail.com>

* Add custom transport check

* Revert changes

* Modify README with extend targets

* Modify custom contributions

Co-authored-by: acuadros95 <acuadros1995@gmail.com>

Author: pablogs9

.github/workflows/ci.yml

@@ -14,7 +14,7 @@ jobs:
         strategy:
           fail-fast: false
           matrix:
-            platform: [teensy41, teensy40, teensy36, teensy35, teensy31, due, zero, olimex_e407, esp32dev, nanorp2040connect, portenta_h7_m7, teensy41_eth, nanorp2040connect_wifi, portenta_h7_m7_wifi, esp32dev_wifi, portenta_h7_m7_foxy, portenta_h7_m7_rolling]
+            platform: [teensy41, teensy40, teensy36, teensy35, teensy31, due, zero, olimex_e407, esp32dev, nanorp2040connect, portenta_h7_m7, teensy41_eth, nanorp2040connect_wifi, portenta_h7_m7_wifi, esp32dev_wifi, portenta_h7_m7_foxy, portenta_h7_m7_rolling, teensy41_custom]
 
         steps:
         - uses: actions/checkout@v3

README.md

@@ -16,8 +16,8 @@ PlatformIO will handle the full build process, including dependencies, compilati
     - [Transport configuration](#transport-configuration)
     - [Extra packages](#extra-packages)
     - [Other configuration](#other-configuration)
-  - [Custom targets](#custom-targets)
-    - [Custom transport](#custom-transport)
+  - [Extend library targets](#extend-library-targets)
+    - [Transport implementation](#transport-implementation)
     - [Time source](#time-source)
   - [Using the micro-ROS Agent](#using-the-micro-ros-agent)
   - [Examples](#examples)
@@ -119,6 +119,26 @@ The transport can be configured with the `board_microros_transport = <transport>
     set_microros_native_ethernet_transports(local_mac, local_ip, agent_ip, agent_port);
     ```
 
+  - `custom`
+
+    The user will need to write transport functions in app code and provide it to the micro-ROS library using [`rmw_uros_set_custom_transport()` API](https://micro.ros.org/docs/tutorials/advanced/create_custom_transports/)
+
+    ```c
+    bool platformio_transport_open(struct uxrCustomTransport * transport) {...};
+    bool platformio_transport_close(struct uxrCustomTransport * transport) {...};
+    size_t platformio_transport_write(struct uxrCustomTransport* transport, const uint8_t * buf, size_t len, uint8_t * err) {...};
+    size_t platformio_transport_read(struct uxrCustomTransport* transport, uint8_t* buf, size_t len, int timeout, uint8_t* err) {...};
+
+    rmw_uros_set_custom_transport(
+      MICROROS_TRANSPORTS_FRAMING_MODE, // Set the MICROROS_TRANSPORTS_FRAMING_MODE or MICROROS_TRANSPORTS_PACKET_MODE mode accordingly
+      NULL,
+      platformio_transport_open,
+      platformio_transport_close,
+      platformio_transport_write,
+      platformio_transport_read
+    );
+    ```
+
 ### Extra packages
 Colcon packages can be added to the build process using this two methods:
 - Package directories copied on the `<Project_directory>/extra_packages` folder.
@@ -136,12 +156,12 @@ This allows the user to customize the library memory resources or activate optio
 
   *Note: the [common.meta](./metas/common.meta) file makes general adjustments to the library and shall not be modified by the user.*
 
-## Custom targets
+## Extend library targets
 This library can be easily adapted to different boards, transports or RTOS, to achieve this the user shall provide:
 
-### Custom transport
+### Transport implementation
 
-Custom transport shall follow the signatures shown on [micro_ros_platformio.h](./platform_code/arduino/micro_ros_platformio.h), the [provided sources](./platform_code) can be used as reference along [this documentation](https://micro-xrce-dds.docs.eprosima.com/en/latest/transport.html#custom-transport). Custom transport source code shall be added on the `./platform_code/<framework>/<board_microros_transport>` path. Example:
+New transport implementations shall follow the signatures shown on [micro_ros_platformio.h](./platform_code/arduino/micro_ros_platformio.h), the [provided sources](./platform_code) can be used as reference along [this documentation](https://micro-xrce-dds.docs.eprosima.com/en/latest/transport.html#custom-transport). Contributed transport source code shall be added on the `./platform_code/<framework>/<board_microros_transport>` path. Example:
 
 - `platform.ini`:
   ```ini
@@ -152,6 +172,8 @@ Custom transport shall follow the signatures shown on [micro_ros_platformio.h](.
 - Also, a `MICRO_ROS_TRANSPORT_<FRAMEWORK>_<TRANSPORT>` definition will be available:
   https://github.com/micro-ROS/micro_ros_platformio/blob/de7a61c7e86fdd0186ed8b7d8ec320994e8ebcbf/ci/src/main.cpp#L3
 
+  *Note: `board_microros_transport = custom` should not be used, as it is used to add custom transports on user app code*
+
 ### Time source
 micro-ROS needs a time source to handle executor spins and synchronize reliable communication. To achieve this, a `clock_gettime` [POSIX compliant](https://linux.die.net/man/3/clock_gettime) implementation is required, with a minimum resolution of 1 millisecond.
 

ci/platformio.ini

@@ -145,3 +145,13 @@ board_microros_transport = wifi_nina
 lib_deps =
     arduino-libraries/WiFiNINA@^1.8.13
     ../
+
+; Custom transports
+
+[env:teensy41_custom]
+platform = teensy
+board = teensy41
+framework = arduino
+board_microros_transport = custom
+lib_deps =
+    ../

ci/src/main.cpp

@@ -14,6 +14,14 @@
 
 #include <std_msgs/msg/int32.h>
 
+// Test custom transports
+#if defined(MICRO_ROS_TRANSPORT_ARDUINO_CUSTOM)
+bool platformio_transport_open(struct uxrCustomTransport * transport) {return false;};
+bool platformio_transport_close(struct uxrCustomTransport * transport) {return false;};
+size_t platformio_transport_write(struct uxrCustomTransport* transport, const uint8_t * buf, size_t len, uint8_t * err) {return 0;};
+size_t platformio_transport_read(struct uxrCustomTransport* transport, uint8_t* buf, size_t len, int timeout, uint8_t* err) {return 0;};
+#endif
+
 // Test extra packages
 #include <control_msgs/msg/joint_controller_state.h>
 #include <my_custom_message/msg/my_custom_message.h>
@@ -70,6 +78,15 @@ void setup() {
   char psk[]= "WIFI_PSK";
 
   set_microros_wifi_transports(ssid, psk, agent_ip, agent_port);
+#elif defined(MICRO_ROS_TRANSPORT_ARDUINO_CUSTOM)
+  rmw_uros_set_custom_transport(
+    MICROROS_TRANSPORTS_FRAMING_MODE,
+    NULL,
+    platformio_transport_open,
+    platformio_transport_close,
+    platformio_transport_write,
+    platformio_transport_read
+  );
 #else
 #error "No transport defined"
 #endif

extra_script.py

@@ -136,7 +136,7 @@ def build_microros(*args, **kwargs):
     global_env.Append(CPPPATH=[main_path + "/platform_code/{}".format(framework)])
 
     # Add clock implementation
-    env['SRC_FILTER'] += ' +<platform_code/{}/clock_gettime.cpp>'.format(framework, )
+    env['SRC_FILTER'] += ' +<platform_code/{}/clock_gettime.cpp>'.format(framework)
 
     # Add transport sources according to the framework and the transport
     env['SRC_FILTER'] += ' +<platform_code/{}/{}/micro_ros_transport.cpp>'.format(framework, microros_transport)