From 73fa3dabcc41f23cee8b085f409c28810d5737c5 Mon Sep 17 00:00:00 2001 From: Pablo Garrido Date: Mon, 1 Mar 2021 08:10:13 +0100 Subject: [PATCH 01/29] Add custom transport tutorial --- _data/docs.yml | 1 + .../create_custom_transports/index.md | 207 ++++++++++++++++++ 2 files changed, 208 insertions(+) create mode 100644 _docs/tutorials/advanced/create_custom_transports/index.md diff --git a/_data/docs.yml b/_data/docs.yml index 6526f889..734047a3 100644 --- a/_data/docs.yml +++ b/_data/docs.yml @@ -62,6 +62,7 @@ - tutorials/advanced/benchmarking - tutorials/advanced/zephyr_emulator - tutorials/advanced/create_custom_static_library + - tutorials/advanced/create_custom_transports - title: Demos docs: diff --git a/_docs/tutorials/advanced/create_custom_transports/index.md b/_docs/tutorials/advanced/create_custom_transports/index.md new file mode 100644 index 00000000..dd586624 --- /dev/null +++ b/_docs/tutorials/advanced/create_custom_transports/index.md @@ -0,0 +1,207 @@ +--- +title: Creating custom micro-ROS transports +permalink: /docs/tutorials/advanced/create_custom_transports/ +--- + +This tutorial aims at providing step-by-step guidance for those users interested in creating micro-ROS custom transports different from the one provided by default in the micro-ROS tools. + +This tutorial starts in a previously created micro-ROS environment. Check the first steps of [**First micro-ROS application on an RTOS**](../../core/first_application_rtos/) for instructions on how to create a micro-ROS environment for embedded platforms. + +The micro-ROS middleware, *eProsima Micro XRCE-DDS*, provides a user API that allows interfacing with the lowest level transport layer at runtime, +which enables users to implement their own transports in both the micro-ROS Client and micro-ROS Agent libraries. +Thanks to this, the Micro XRCE-DDS wire protocol can be transmitted over virtually any protocol, network or communication +mechanism. In order to do so, two general communication modes are provided: + +* **Stream-oriented mode**: the communication mechanism implemented does not have the concept of packet. + [HDLC framing](https://micro-xrce-dds.docs.eprosima.com/en/latest/transport.html?highlight=hdlc#custom-serial-transport) will be used. +* **Packet-oriented mode**: the communication mechanism implemented is able to send a whole packet that includes an XRCE message. + +These two modes can be selected by activating and deactivating the `framing` parameter in both the micro-ROS Client and the micro-ROS Agent functions. + +## micro-ROS Client + +An example on how to set these external transport callbacks in the micro-ROS Client API is: + +```c +#include + +... + +struct custom_args { + ... +} + +struct custom_args args; + +rmw_uros_set_custom_transport( + true, // Framing enabled here. Using Stream-oriented mode. + (void *) &args, + arduino_transport_open, + arduino_transport_close, + arduino_transport_write, + arduino_transport_read +); +``` + +It is important to notice that in `rmw_uros_set_custom_transport` a pointer to custom arguments is set. This reference will be available to every callbacks call. + +In general, four functions need to be implemented. The behavior of these functions is sightly different, depending on the selected mode: + +### Open function + +```c +bool my_custom_transport_open(uxrCustomTransport* transport) +{ + ... +} +``` +This function should open and init the custom transport. It returns a boolean indicating if the opening was successful. +`transport->args` have the arguments passed through `uxr_init_custom_transport`. + +### Close function +```c +bool my_custom_transport_close(uxrCustomTransport* transport) +{ + ... +} +``` +This function should close the custom transport. It returns a boolean indicating if closing was successful. +`transport->args` have the arguments passed through `uxr_init_custom_transport`. + +### Write function +```c +size_t my_custom_transport_write( + uxrCustomTransport* transport, + const uint8_t* buffer, + size_t length, + uint8_t* errcode) +{ + ... +} +``` +This function should write data to the custom transport. It returns the number of Bytes written. +`transport->args` have the arguments passed through `uxr_init_custom_transport`. + +* **Stream-oriented mode:** The function can send up to `length` Bytes from `buffer`. + +* **Packet-oriented mode:** The function should send `length` Bytes from `buffer`. If less than `length` Bytes are written `errcode` can be set. + +### Read function +```c +size_t my_custom_transport_read( + uxrCustomTransport* transport, + uint8_t* buffer, + size_t length, + int timeout, + uint8_t* errcode) +{ + ... +} +``` +This function should read data to the custom transport. It returns the number of Bytes read +`transport->args` have the arguments passed through `uxr_init_custom_transport`. + +* **Stream-oriented mode:** The function should retrieve up to `length` Bytes from transport + and write them into `buffer` in `timeout` milliseconds. + +* **Packet-oriented mode:** The function should retrieve `length` Bytes from transport + and write them into `buffer` in `timeout` milliseconds. If less than `length` Bytes are read `errcode` can be set. + + + +## Micro XRCE-DDS Agent + +The micro-ROS Agent profile for custom transports is enabled by default. + +An example on how to set the external transport callbacks in the micro-ROS Agent API is: + +```cpp +eprosima::uxr::Middleware::Kind mw_kind(eprosima::uxr::Middleware::Kind::FASTDDS); +eprosima::uxr::CustomEndPoint custom_endpoint; + +// Add transport endpoing parameters +custom_endpoint.add_member("param1"); +custom_endpoint.add_member("param2"); +custom_endpoint.add_member("param3"); + +eprosima::uxr::CustomAgent custom_agent( + "my_custom_transport", + &custom_endpoint, + mw_kind, + true, // Framing enabled here. Using Stream-oriented mode. + my_custom_transport_open, + my_custom_transport_close, + my_custom_transport_write + my_custom_transport_read); + +custom_agent.start(); +``` + +The `custom_endpoint` is the object in charge of handling the endpoint parameters. The *Agent*, unlike the *Client*, can receive +messages from multiple *Clients* so it must be able to differentiate between different *Clients*. +Therefore, the `eprosima::uxr::CustomEndPoint` should be provided with information about the origin of the message +in the read callback, and with information about the destination of the message in the write callback. + +In general, members of a `eprosima::uxr::CustomEndPoint` object can be unsigned integers and strings. + +As in the *Client* API, four functions should be implemented. The behavior of these functions is sightly different +depending on the selected mode: + +### Open function +```cpp +eprosima::uxr::CustomAgent::InitFunction my_custom_transport_open = [&]() -> bool +{ + ... +} +``` +This function should open and init the custom transport. It returns a boolean indicating if the opening was successful. + +### Close function +```cpp +eprosima::uxr::CustomAgent::FiniFunction my_custom_transport_close = [&]() -> bool +{ + ... +} +``` +This function should close the custom transport. It returns a boolean indicating if the closing was successful. + +### Write function +```cpp +eprosima::uxr::CustomAgent::SendMsgFunction my_custom_transport_write = [&]( + const eprosima::uxr::CustomEndPoint* destination_endpoint, + uint8_t* buffer, + size_t length, + eprosima::uxr::TransportRc& transport_rc) -> ssize_t +{ + ... +} +``` +This function should write data to the custom transport. It must use +the `destination_endpoint` members to set the data destination. It returns the number of Bytes written. +It should set `transport_rc` indicating the result of the operation. + +* **Stream-oriented mode:** The function can send up to `length` Bytes from `buffer`. + +* **Packet-oriented mode:** The function should send `length` Bytes from `buffer`. If less than `length` Bytes are written, `transport_rc` can be set. + +### Read function +```cpp +eprosima::uxr::CustomAgent::RecvMsgFunction my_custom_transport_read = [&]( + eprosima::uxr::CustomEndPoint* source_endpoint, + uint8_t* buffer, + size_t length, + int timeout, + eprosima::uxr::TransportRc& transport_rc) -> ssize_t +{ + ... +} +``` +This function should read data to the custom transport. It must fill `source_endpoint` members with data source. +It returns the number of Bytes read. +It should set `transport_rc` indicating the result of the operation. + +* **Stream-oriented mode:** The function should retrieve up to `length` Bytes from transport + and write them into `buffer` in `timeout` milliseconds. + +* **Packet-oriented mode:** The function should retrieve `length` Bytes from transport + and write them into `buffer` in `timeout` milliseconds. If less than `length` Bytes are read transport_rc can be set. From ed3349f0ffbb0fec768757a0a7090e11b1ecc117 Mon Sep 17 00:00:00 2001 From: Pablo Garrido Date: Mon, 1 Mar 2021 10:37:07 +0100 Subject: [PATCH 02/29] Update --- .../tutorials/advanced/create_custom_transports/index.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/_docs/tutorials/advanced/create_custom_transports/index.md b/_docs/tutorials/advanced/create_custom_transports/index.md index dd586624..135d3a3e 100644 --- a/_docs/tutorials/advanced/create_custom_transports/index.md +++ b/_docs/tutorials/advanced/create_custom_transports/index.md @@ -36,10 +36,10 @@ struct custom_args args; rmw_uros_set_custom_transport( true, // Framing enabled here. Using Stream-oriented mode. (void *) &args, - arduino_transport_open, - arduino_transport_close, - arduino_transport_write, - arduino_transport_read + my_custom_transport_open, + my_custom_transport_close, + my_custom_transport_write, + my_custom_transport_read ); ``` From d60e95d9ca2fc7a70a47ba89f2bdb8d2b17e2984 Mon Sep 17 00:00:00 2001 From: Pablo Garrido Date: Mon, 1 Mar 2021 11:07:17 +0100 Subject: [PATCH 03/29] Update _docs/tutorials/advanced/create_custom_transports/index.md Co-authored-by: Jose Antonio Moral --- _docs/tutorials/advanced/create_custom_transports/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_docs/tutorials/advanced/create_custom_transports/index.md b/_docs/tutorials/advanced/create_custom_transports/index.md index 135d3a3e..b8dcb981 100644 --- a/_docs/tutorials/advanced/create_custom_transports/index.md +++ b/_docs/tutorials/advanced/create_custom_transports/index.md @@ -3,7 +3,7 @@ title: Creating custom micro-ROS transports permalink: /docs/tutorials/advanced/create_custom_transports/ --- -This tutorial aims at providing step-by-step guidance for those users interested in creating micro-ROS custom transports different from the one provided by default in the micro-ROS tools. +This tutorial aims at providing step-by-step guidance for those users interested in creating micro-ROS custom transports, instead of using the ones provided by default in the micro-ROS tools set. This tutorial starts in a previously created micro-ROS environment. Check the first steps of [**First micro-ROS application on an RTOS**](../../core/first_application_rtos/) for instructions on how to create a micro-ROS environment for embedded platforms. From 5f372ee84572a3a35c5842e8ce8ef1c1a5845008 Mon Sep 17 00:00:00 2001 From: Pablo Garrido Date: Mon, 1 Mar 2021 11:07:23 +0100 Subject: [PATCH 04/29] Update _docs/tutorials/advanced/create_custom_transports/index.md Co-authored-by: Jose Antonio Moral --- _docs/tutorials/advanced/create_custom_transports/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_docs/tutorials/advanced/create_custom_transports/index.md b/_docs/tutorials/advanced/create_custom_transports/index.md index b8dcb981..d98148fb 100644 --- a/_docs/tutorials/advanced/create_custom_transports/index.md +++ b/_docs/tutorials/advanced/create_custom_transports/index.md @@ -5,7 +5,7 @@ permalink: /docs/tutorials/advanced/create_custom_transports/ This tutorial aims at providing step-by-step guidance for those users interested in creating micro-ROS custom transports, instead of using the ones provided by default in the micro-ROS tools set. -This tutorial starts in a previously created micro-ROS environment. Check the first steps of [**First micro-ROS application on an RTOS**](../../core/first_application_rtos/) for instructions on how to create a micro-ROS environment for embedded platforms. +This tutorial starts from a previously created micro-ROS environment. Check the first steps of [**First micro-ROS application on an RTOS**](../../core/first_application_rtos/) for instructions on how to create a micro-ROS environment for embedded platforms. The micro-ROS middleware, *eProsima Micro XRCE-DDS*, provides a user API that allows interfacing with the lowest level transport layer at runtime, which enables users to implement their own transports in both the micro-ROS Client and micro-ROS Agent libraries. From 45d6a5acf78ffc8501113d795b8fe9b370d00c6d Mon Sep 17 00:00:00 2001 From: Pablo Garrido Date: Mon, 1 Mar 2021 11:07:31 +0100 Subject: [PATCH 05/29] Update _docs/tutorials/advanced/create_custom_transports/index.md Co-authored-by: Jose Antonio Moral --- _docs/tutorials/advanced/create_custom_transports/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_docs/tutorials/advanced/create_custom_transports/index.md b/_docs/tutorials/advanced/create_custom_transports/index.md index d98148fb..123b0b89 100644 --- a/_docs/tutorials/advanced/create_custom_transports/index.md +++ b/_docs/tutorials/advanced/create_custom_transports/index.md @@ -45,7 +45,7 @@ rmw_uros_set_custom_transport( It is important to notice that in `rmw_uros_set_custom_transport` a pointer to custom arguments is set. This reference will be available to every callbacks call. -In general, four functions need to be implemented. The behavior of these functions is sightly different, depending on the selected mode: +In general, four functions must be implemented. The behaviour of these functions is slightly different, depending on the selected mode: ### Open function From e5baab1c7dd5293e0682c36c76c4d8ba22a5b891 Mon Sep 17 00:00:00 2001 From: Pablo Garrido Date: Mon, 1 Mar 2021 11:07:39 +0100 Subject: [PATCH 06/29] Update _docs/tutorials/advanced/create_custom_transports/index.md Co-authored-by: Jose Antonio Moral --- _docs/tutorials/advanced/create_custom_transports/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_docs/tutorials/advanced/create_custom_transports/index.md b/_docs/tutorials/advanced/create_custom_transports/index.md index 123b0b89..153e9752 100644 --- a/_docs/tutorials/advanced/create_custom_transports/index.md +++ b/_docs/tutorials/advanced/create_custom_transports/index.md @@ -56,7 +56,7 @@ bool my_custom_transport_open(uxrCustomTransport* transport) } ``` This function should open and init the custom transport. It returns a boolean indicating if the opening was successful. -`transport->args` have the arguments passed through `uxr_init_custom_transport`. +`transport->args` holds the arguments passed through `uxr_init_custom_transport`. ### Close function ```c From c5170e76bef073772b51278b574b692d61aede33 Mon Sep 17 00:00:00 2001 From: Pablo Garrido Date: Mon, 1 Mar 2021 11:07:45 +0100 Subject: [PATCH 07/29] Update _docs/tutorials/advanced/create_custom_transports/index.md Co-authored-by: Jose Antonio Moral --- _docs/tutorials/advanced/create_custom_transports/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_docs/tutorials/advanced/create_custom_transports/index.md b/_docs/tutorials/advanced/create_custom_transports/index.md index 153e9752..c5f67fb6 100644 --- a/_docs/tutorials/advanced/create_custom_transports/index.md +++ b/_docs/tutorials/advanced/create_custom_transports/index.md @@ -80,7 +80,7 @@ size_t my_custom_transport_write( } ``` This function should write data to the custom transport. It returns the number of Bytes written. -`transport->args` have the arguments passed through `uxr_init_custom_transport`. +`transport->args` holds the arguments passed through `uxr_init_custom_transport`. * **Stream-oriented mode:** The function can send up to `length` Bytes from `buffer`. From 6c799f12ba562a6a0acba70120851131617626c2 Mon Sep 17 00:00:00 2001 From: Pablo Garrido Date: Mon, 1 Mar 2021 11:07:50 +0100 Subject: [PATCH 08/29] Update _docs/tutorials/advanced/create_custom_transports/index.md Co-authored-by: Jose Antonio Moral --- _docs/tutorials/advanced/create_custom_transports/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_docs/tutorials/advanced/create_custom_transports/index.md b/_docs/tutorials/advanced/create_custom_transports/index.md index c5f67fb6..1056f16b 100644 --- a/_docs/tutorials/advanced/create_custom_transports/index.md +++ b/_docs/tutorials/advanced/create_custom_transports/index.md @@ -66,7 +66,7 @@ bool my_custom_transport_close(uxrCustomTransport* transport) } ``` This function should close the custom transport. It returns a boolean indicating if closing was successful. -`transport->args` have the arguments passed through `uxr_init_custom_transport`. +`transport->args` holds the arguments passed through `uxr_init_custom_transport`. ### Write function ```c From c70db56ab8be5b63f925379e99a08b0cd5b099f8 Mon Sep 17 00:00:00 2001 From: Pablo Garrido Date: Mon, 1 Mar 2021 11:07:56 +0100 Subject: [PATCH 09/29] Update _docs/tutorials/advanced/create_custom_transports/index.md Co-authored-by: FranFin <58737168+FranFin@users.noreply.github.com> --- _docs/tutorials/advanced/create_custom_transports/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_docs/tutorials/advanced/create_custom_transports/index.md b/_docs/tutorials/advanced/create_custom_transports/index.md index 1056f16b..184cf60d 100644 --- a/_docs/tutorials/advanced/create_custom_transports/index.md +++ b/_docs/tutorials/advanced/create_custom_transports/index.md @@ -79,7 +79,7 @@ size_t my_custom_transport_write( ... } ``` -This function should write data to the custom transport. It returns the number of Bytes written. +This function should write data to the custom transport. It returns the number of bytes written. `transport->args` holds the arguments passed through `uxr_init_custom_transport`. * **Stream-oriented mode:** The function can send up to `length` Bytes from `buffer`. From d781e87fb67f798f018de8ebf436c2dc9ed1b4d3 Mon Sep 17 00:00:00 2001 From: Pablo Garrido Date: Mon, 1 Mar 2021 11:08:02 +0100 Subject: [PATCH 10/29] Update _docs/tutorials/advanced/create_custom_transports/index.md Co-authored-by: FranFin <58737168+FranFin@users.noreply.github.com> --- _docs/tutorials/advanced/create_custom_transports/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_docs/tutorials/advanced/create_custom_transports/index.md b/_docs/tutorials/advanced/create_custom_transports/index.md index 184cf60d..d7fb2e0d 100644 --- a/_docs/tutorials/advanced/create_custom_transports/index.md +++ b/_docs/tutorials/advanced/create_custom_transports/index.md @@ -82,7 +82,7 @@ size_t my_custom_transport_write( This function should write data to the custom transport. It returns the number of bytes written. `transport->args` holds the arguments passed through `uxr_init_custom_transport`. -* **Stream-oriented mode:** The function can send up to `length` Bytes from `buffer`. +* **Stream-oriented mode:** The function can send up to `length` bytes from `buffer`. * **Packet-oriented mode:** The function should send `length` Bytes from `buffer`. If less than `length` Bytes are written `errcode` can be set. From 383b6be6676a8fc0e49e70806be754811e476e73 Mon Sep 17 00:00:00 2001 From: Pablo Garrido Date: Mon, 1 Mar 2021 11:08:13 +0100 Subject: [PATCH 11/29] Update _docs/tutorials/advanced/create_custom_transports/index.md Co-authored-by: FranFin <58737168+FranFin@users.noreply.github.com> --- _docs/tutorials/advanced/create_custom_transports/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_docs/tutorials/advanced/create_custom_transports/index.md b/_docs/tutorials/advanced/create_custom_transports/index.md index d7fb2e0d..feb333f8 100644 --- a/_docs/tutorials/advanced/create_custom_transports/index.md +++ b/_docs/tutorials/advanced/create_custom_transports/index.md @@ -98,7 +98,7 @@ size_t my_custom_transport_read( ... } ``` -This function should read data to the custom transport. It returns the number of Bytes read +This function should read data from the custom transport. It returns the number of bytes read. `transport->args` have the arguments passed through `uxr_init_custom_transport`. * **Stream-oriented mode:** The function should retrieve up to `length` Bytes from transport From 9288e357232a666196716b5338f4fdf06898aa75 Mon Sep 17 00:00:00 2001 From: Pablo Garrido Date: Mon, 1 Mar 2021 11:08:18 +0100 Subject: [PATCH 12/29] Update _docs/tutorials/advanced/create_custom_transports/index.md Co-authored-by: FranFin <58737168+FranFin@users.noreply.github.com> --- _docs/tutorials/advanced/create_custom_transports/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_docs/tutorials/advanced/create_custom_transports/index.md b/_docs/tutorials/advanced/create_custom_transports/index.md index feb333f8..b05ab674 100644 --- a/_docs/tutorials/advanced/create_custom_transports/index.md +++ b/_docs/tutorials/advanced/create_custom_transports/index.md @@ -101,7 +101,7 @@ size_t my_custom_transport_read( This function should read data from the custom transport. It returns the number of bytes read. `transport->args` have the arguments passed through `uxr_init_custom_transport`. -* **Stream-oriented mode:** The function should retrieve up to `length` Bytes from transport +* **Stream-oriented mode:** The function should retrieve up to `length` bytes from the transport and write them into `buffer` in `timeout` milliseconds. * **Packet-oriented mode:** The function should retrieve `length` Bytes from transport From de7239fe501931767491a23bef2c8bd094249b76 Mon Sep 17 00:00:00 2001 From: Pablo Garrido Date: Mon, 1 Mar 2021 11:08:24 +0100 Subject: [PATCH 13/29] Update _docs/tutorials/advanced/create_custom_transports/index.md Co-authored-by: FranFin <58737168+FranFin@users.noreply.github.com> --- _docs/tutorials/advanced/create_custom_transports/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_docs/tutorials/advanced/create_custom_transports/index.md b/_docs/tutorials/advanced/create_custom_transports/index.md index b05ab674..5bffe34e 100644 --- a/_docs/tutorials/advanced/create_custom_transports/index.md +++ b/_docs/tutorials/advanced/create_custom_transports/index.md @@ -105,7 +105,7 @@ This function should read data from the custom transport. It returns the number and write them into `buffer` in `timeout` milliseconds. * **Packet-oriented mode:** The function should retrieve `length` Bytes from transport - and write them into `buffer` in `timeout` milliseconds. If less than `length` Bytes are read `errcode` can be set. + and write them into `buffer` in `timeout` milliseconds. If less than `length` bytes are read, `errcode` can be set. From e2b4cd59fbd6f89ce71cadd90da395cb6ea0261c Mon Sep 17 00:00:00 2001 From: Pablo Garrido Date: Mon, 1 Mar 2021 11:08:33 +0100 Subject: [PATCH 14/29] Update _docs/tutorials/advanced/create_custom_transports/index.md Co-authored-by: FranFin <58737168+FranFin@users.noreply.github.com> --- _docs/tutorials/advanced/create_custom_transports/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_docs/tutorials/advanced/create_custom_transports/index.md b/_docs/tutorials/advanced/create_custom_transports/index.md index 5bffe34e..a21bb440 100644 --- a/_docs/tutorials/advanced/create_custom_transports/index.md +++ b/_docs/tutorials/advanced/create_custom_transports/index.md @@ -84,7 +84,7 @@ This function should write data to the custom transport. It returns the number o * **Stream-oriented mode:** The function can send up to `length` bytes from `buffer`. -* **Packet-oriented mode:** The function should send `length` Bytes from `buffer`. If less than `length` Bytes are written `errcode` can be set. +* **Packet-oriented mode:** The function should send `length` bytes from `buffer`. If less than `length` bytes are written, `errcode` can be set. ### Read function ```c From 0d6016ec6d388f449aec23f6621276132caa68e8 Mon Sep 17 00:00:00 2001 From: Pablo Garrido Date: Mon, 1 Mar 2021 11:08:40 +0100 Subject: [PATCH 15/29] Update _docs/tutorials/advanced/create_custom_transports/index.md Co-authored-by: FranFin <58737168+FranFin@users.noreply.github.com> --- _docs/tutorials/advanced/create_custom_transports/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_docs/tutorials/advanced/create_custom_transports/index.md b/_docs/tutorials/advanced/create_custom_transports/index.md index a21bb440..0e613261 100644 --- a/_docs/tutorials/advanced/create_custom_transports/index.md +++ b/_docs/tutorials/advanced/create_custom_transports/index.md @@ -177,7 +177,7 @@ eprosima::uxr::CustomAgent::SendMsgFunction my_custom_transport_write = [&]( } ``` This function should write data to the custom transport. It must use -the `destination_endpoint` members to set the data destination. It returns the number of Bytes written. +the `destination_endpoint` members to set the data destination. It returns the number of bytes written. It should set `transport_rc` indicating the result of the operation. * **Stream-oriented mode:** The function can send up to `length` Bytes from `buffer`. From 86b5096a6ac147bdcdffe018302fad3be618a47a Mon Sep 17 00:00:00 2001 From: Pablo Garrido Date: Mon, 1 Mar 2021 11:08:45 +0100 Subject: [PATCH 16/29] Update _docs/tutorials/advanced/create_custom_transports/index.md Co-authored-by: FranFin <58737168+FranFin@users.noreply.github.com> --- _docs/tutorials/advanced/create_custom_transports/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_docs/tutorials/advanced/create_custom_transports/index.md b/_docs/tutorials/advanced/create_custom_transports/index.md index 0e613261..a5cb5d38 100644 --- a/_docs/tutorials/advanced/create_custom_transports/index.md +++ b/_docs/tutorials/advanced/create_custom_transports/index.md @@ -197,7 +197,7 @@ eprosima::uxr::CustomAgent::RecvMsgFunction my_custom_transport_read = [&]( } ``` This function should read data to the custom transport. It must fill `source_endpoint` members with data source. -It returns the number of Bytes read. +It returns the number of bytes read. It should set `transport_rc` indicating the result of the operation. * **Stream-oriented mode:** The function should retrieve up to `length` Bytes from transport From 3bbb2e653792b855e21dc1dd6496f8f59b78051e Mon Sep 17 00:00:00 2001 From: Pablo Garrido Date: Mon, 1 Mar 2021 11:08:50 +0100 Subject: [PATCH 17/29] Update _docs/tutorials/advanced/create_custom_transports/index.md Co-authored-by: FranFin <58737168+FranFin@users.noreply.github.com> --- _docs/tutorials/advanced/create_custom_transports/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_docs/tutorials/advanced/create_custom_transports/index.md b/_docs/tutorials/advanced/create_custom_transports/index.md index a5cb5d38..2edbbc43 100644 --- a/_docs/tutorials/advanced/create_custom_transports/index.md +++ b/_docs/tutorials/advanced/create_custom_transports/index.md @@ -200,7 +200,7 @@ This function should read data to the custom transport. It must fill `source_end It returns the number of bytes read. It should set `transport_rc` indicating the result of the operation. -* **Stream-oriented mode:** The function should retrieve up to `length` Bytes from transport +* **Stream-oriented mode:** The function should retrieve up to `length` bytes from the transport and write them into `buffer` in `timeout` milliseconds. * **Packet-oriented mode:** The function should retrieve `length` Bytes from transport From bf78a5658ca568e167690241c65a746e237a1931 Mon Sep 17 00:00:00 2001 From: Pablo Garrido Date: Mon, 1 Mar 2021 11:08:55 +0100 Subject: [PATCH 18/29] Update _docs/tutorials/advanced/create_custom_transports/index.md Co-authored-by: FranFin <58737168+FranFin@users.noreply.github.com> --- _docs/tutorials/advanced/create_custom_transports/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_docs/tutorials/advanced/create_custom_transports/index.md b/_docs/tutorials/advanced/create_custom_transports/index.md index 2edbbc43..da72f3e6 100644 --- a/_docs/tutorials/advanced/create_custom_transports/index.md +++ b/_docs/tutorials/advanced/create_custom_transports/index.md @@ -204,4 +204,4 @@ It should set `transport_rc` indicating the result of the operation. and write them into `buffer` in `timeout` milliseconds. * **Packet-oriented mode:** The function should retrieve `length` Bytes from transport - and write them into `buffer` in `timeout` milliseconds. If less than `length` Bytes are read transport_rc can be set. + and write them into `buffer` in `timeout` milliseconds. If less than `length` bytes are read, `transport_rc` can be set. From 98625d65d91da8a50e21edfe5e0b7caa2d4026a5 Mon Sep 17 00:00:00 2001 From: Pablo Garrido Date: Mon, 1 Mar 2021 11:08:59 +0100 Subject: [PATCH 19/29] Update _docs/tutorials/advanced/create_custom_transports/index.md Co-authored-by: FranFin <58737168+FranFin@users.noreply.github.com> --- _docs/tutorials/advanced/create_custom_transports/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_docs/tutorials/advanced/create_custom_transports/index.md b/_docs/tutorials/advanced/create_custom_transports/index.md index da72f3e6..1b4309e2 100644 --- a/_docs/tutorials/advanced/create_custom_transports/index.md +++ b/_docs/tutorials/advanced/create_custom_transports/index.md @@ -203,5 +203,5 @@ It should set `transport_rc` indicating the result of the operation. * **Stream-oriented mode:** The function should retrieve up to `length` bytes from the transport and write them into `buffer` in `timeout` milliseconds. -* **Packet-oriented mode:** The function should retrieve `length` Bytes from transport +* **Packet-oriented mode:** The function should retrieve `length` bytes from the transport and write them into `buffer` in `timeout` milliseconds. If less than `length` bytes are read, `transport_rc` can be set. From 43fbbb962081b08cdd9e9385a083f3a6f0748bb1 Mon Sep 17 00:00:00 2001 From: Pablo Garrido Date: Mon, 1 Mar 2021 11:15:49 +0100 Subject: [PATCH 20/29] Add jose's endpoints --- .../create_custom_transports/index.md | 39 +++++++++++++++++-- 1 file changed, 36 insertions(+), 3 deletions(-) diff --git a/_docs/tutorials/advanced/create_custom_transports/index.md b/_docs/tutorials/advanced/create_custom_transports/index.md index 1b4309e2..20f9429c 100644 --- a/_docs/tutorials/advanced/create_custom_transports/index.md +++ b/_docs/tutorials/advanced/create_custom_transports/index.md @@ -136,16 +136,49 @@ eprosima::uxr::CustomAgent custom_agent( custom_agent.start(); ``` +As in the *Client* API, four functions should be implemented. The behavior of these functions is sightly different +depending on the selected mode. +### CustomEndPoint -The `custom_endpoint` is the object in charge of handling the endpoint parameters. The *Agent*, unlike the *Client*, can receive +The `custom_endpoint` is an object of type `eprosima::uxr::CustomEndPoint` and it us in charge of handling the endpoint parameters. The *Agent*, unlike the *Client*, can receive messages from multiple *Clients* so it must be able to differentiate between different *Clients*. Therefore, the `eprosima::uxr::CustomEndPoint` should be provided with information about the origin of the message in the read callback, and with information about the destination of the message in the write callback. In general, members of a `eprosima::uxr::CustomEndPoint` object can be unsigned integers and strings. -As in the *Client* API, four functions should be implemented. The behavior of these functions is sightly different -depending on the selected mode: +`CustomEndPoint` defines three methods: + +Add member +```cpp +bool eprosima::uxr::CustomEndPoint::add_member<*KIND*>(const std::string& member_name); +``` +Allows to dynamically add a new member to the endpoint definition. + +Returns `true` if member was correctly added, or `false` if something went wrong (for example, the member already existed). + +- **KIND**: To be chosen from: `uint8_t`, `uint16_t`, `uint32_t`, `uint64_t`, `uint128_t` or `std::string`. +- **member_name**: The tag used to identify the endpoint member. + +Set member value +```cpp +void eprosima::uxr::CustomEndPoint::set_member_value(const std::string& member_name, const *KIND* & value); +``` + +Sets the specific value (numeric or string) for a certain member, which must previously exist in the CustomEndPoint. + +- **member_name**: The member whose value is going to be modified. +- **value**: The value to be set, of `KIND`: `uint8_t`, `uint16_t`, `uint32_t`, `uint64_t`, `uint128_t` or `std::string`. + +Get member +```cpp +const *KIND* & eprosima::uxr::CustomEndPoint::get_member(const std::string& member_name); +``` + +Gets the current value of the member registered with the given parameter. +The retrieved value might be an `uint8_t`, `uint16_t`, `uint32_t`, `uint64_t`, `uint128_t` or `std::string`. + +- **member_name**: The `CustomEndPoint` member name whose current value is requested. ### Open function ```cpp From 7c29608ea88c4f5fb0600e07b1289c38d856e031 Mon Sep 17 00:00:00 2001 From: Pablo Garrido Date: Mon, 1 Mar 2021 11:16:25 +0100 Subject: [PATCH 21/29] Update _docs/tutorials/advanced/create_custom_transports/index.md Co-authored-by: FranFin <58737168+FranFin@users.noreply.github.com> --- _docs/tutorials/advanced/create_custom_transports/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_docs/tutorials/advanced/create_custom_transports/index.md b/_docs/tutorials/advanced/create_custom_transports/index.md index 20f9429c..b7535690 100644 --- a/_docs/tutorials/advanced/create_custom_transports/index.md +++ b/_docs/tutorials/advanced/create_custom_transports/index.md @@ -215,7 +215,7 @@ It should set `transport_rc` indicating the result of the operation. * **Stream-oriented mode:** The function can send up to `length` Bytes from `buffer`. -* **Packet-oriented mode:** The function should send `length` Bytes from `buffer`. If less than `length` Bytes are written, `transport_rc` can be set. +* **Packet-oriented mode:** The function should send `length` Bytes from `buffer`. If less than `length` bytes are written, `transport_rc` can be set. ### Read function ```cpp From 9de8ecda2ac0782bb4cf327289568bb8b110a1c8 Mon Sep 17 00:00:00 2001 From: Pablo Garrido Date: Mon, 1 Mar 2021 12:38:32 +0100 Subject: [PATCH 22/29] Update _docs/tutorials/advanced/create_custom_transports/index.md Co-authored-by: FranFin <58737168+FranFin@users.noreply.github.com> --- _docs/tutorials/advanced/create_custom_transports/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_docs/tutorials/advanced/create_custom_transports/index.md b/_docs/tutorials/advanced/create_custom_transports/index.md index b7535690..809385c8 100644 --- a/_docs/tutorials/advanced/create_custom_transports/index.md +++ b/_docs/tutorials/advanced/create_custom_transports/index.md @@ -145,7 +145,7 @@ messages from multiple *Clients* so it must be able to differentiate between dif Therefore, the `eprosima::uxr::CustomEndPoint` should be provided with information about the origin of the message in the read callback, and with information about the destination of the message in the write callback. -In general, members of a `eprosima::uxr::CustomEndPoint` object can be unsigned integers and strings. +In general, the members of a `eprosima::uxr::CustomEndPoint` object can be unsigned integers and strings. `CustomEndPoint` defines three methods: From 806eba6d3c395ba138d17482a92fecbd58005fdc Mon Sep 17 00:00:00 2001 From: Pablo Garrido Date: Mon, 1 Mar 2021 12:38:40 +0100 Subject: [PATCH 23/29] Update _docs/tutorials/advanced/create_custom_transports/index.md Co-authored-by: FranFin <58737168+FranFin@users.noreply.github.com> --- _docs/tutorials/advanced/create_custom_transports/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_docs/tutorials/advanced/create_custom_transports/index.md b/_docs/tutorials/advanced/create_custom_transports/index.md index 809385c8..bf2e589f 100644 --- a/_docs/tutorials/advanced/create_custom_transports/index.md +++ b/_docs/tutorials/advanced/create_custom_transports/index.md @@ -165,7 +165,7 @@ Set member value void eprosima::uxr::CustomEndPoint::set_member_value(const std::string& member_name, const *KIND* & value); ``` -Sets the specific value (numeric or string) for a certain member, which must previously exist in the CustomEndPoint. +This function sets the specific value (numeric or string) for a certain member, which must previously exist in the `CustomEndPoint`. - **member_name**: The member whose value is going to be modified. - **value**: The value to be set, of `KIND`: `uint8_t`, `uint16_t`, `uint32_t`, `uint64_t`, `uint128_t` or `std::string`. From 1eefe2b6025986fb9a3cc4070df992385cd8df08 Mon Sep 17 00:00:00 2001 From: Pablo Garrido Date: Mon, 1 Mar 2021 12:38:47 +0100 Subject: [PATCH 24/29] Update _docs/tutorials/advanced/create_custom_transports/index.md Co-authored-by: FranFin <58737168+FranFin@users.noreply.github.com> --- _docs/tutorials/advanced/create_custom_transports/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_docs/tutorials/advanced/create_custom_transports/index.md b/_docs/tutorials/advanced/create_custom_transports/index.md index bf2e589f..3a791251 100644 --- a/_docs/tutorials/advanced/create_custom_transports/index.md +++ b/_docs/tutorials/advanced/create_custom_transports/index.md @@ -141,7 +141,7 @@ depending on the selected mode. ### CustomEndPoint The `custom_endpoint` is an object of type `eprosima::uxr::CustomEndPoint` and it us in charge of handling the endpoint parameters. The *Agent*, unlike the *Client*, can receive -messages from multiple *Clients* so it must be able to differentiate between different *Clients*. +messages from multiple *Clients* so it must be able to differentiate between them. Therefore, the `eprosima::uxr::CustomEndPoint` should be provided with information about the origin of the message in the read callback, and with information about the destination of the message in the write callback. From 4255a4e1b579bad8ec7e38105a270f35ea14a98f Mon Sep 17 00:00:00 2001 From: Pablo Garrido Date: Mon, 1 Mar 2021 12:38:55 +0100 Subject: [PATCH 25/29] Update _docs/tutorials/advanced/create_custom_transports/index.md Co-authored-by: FranFin <58737168+FranFin@users.noreply.github.com> --- _docs/tutorials/advanced/create_custom_transports/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_docs/tutorials/advanced/create_custom_transports/index.md b/_docs/tutorials/advanced/create_custom_transports/index.md index 3a791251..866e90dd 100644 --- a/_docs/tutorials/advanced/create_custom_transports/index.md +++ b/_docs/tutorials/advanced/create_custom_transports/index.md @@ -155,7 +155,7 @@ bool eprosima::uxr::CustomEndPoint::add_member<*KIND*>(const std::string& member ``` Allows to dynamically add a new member to the endpoint definition. -Returns `true` if member was correctly added, or `false` if something went wrong (for example, the member already existed). +Ir returns ``true`` if the member was correctly added, ``false`` if something went wrong (for example, if the member already exists). - **KIND**: To be chosen from: `uint8_t`, `uint16_t`, `uint32_t`, `uint64_t`, `uint128_t` or `std::string`. - **member_name**: The tag used to identify the endpoint member. From 9f1a2bcef6a0949ecc3c97a76a29608e59ec80cf Mon Sep 17 00:00:00 2001 From: Pablo Garrido Date: Mon, 1 Mar 2021 12:39:02 +0100 Subject: [PATCH 26/29] Update _docs/tutorials/advanced/create_custom_transports/index.md Co-authored-by: FranFin <58737168+FranFin@users.noreply.github.com> --- _docs/tutorials/advanced/create_custom_transports/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_docs/tutorials/advanced/create_custom_transports/index.md b/_docs/tutorials/advanced/create_custom_transports/index.md index 866e90dd..f361abd7 100644 --- a/_docs/tutorials/advanced/create_custom_transports/index.md +++ b/_docs/tutorials/advanced/create_custom_transports/index.md @@ -175,7 +175,7 @@ Get member const *KIND* & eprosima::uxr::CustomEndPoint::get_member(const std::string& member_name); ``` -Gets the current value of the member registered with the given parameter. +This function gets the current value of the member registered with the given parameter. The retrieved value might be an `uint8_t`, `uint16_t`, `uint32_t`, `uint64_t`, `uint128_t` or `std::string`. - **member_name**: The `CustomEndPoint` member name whose current value is requested. From 99d17003910bda4a4f52f614193bbeaf3e4f806b Mon Sep 17 00:00:00 2001 From: Pablo Garrido Date: Mon, 1 Mar 2021 12:39:08 +0100 Subject: [PATCH 27/29] Update _docs/tutorials/advanced/create_custom_transports/index.md Co-authored-by: FranFin <58737168+FranFin@users.noreply.github.com> --- _docs/tutorials/advanced/create_custom_transports/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_docs/tutorials/advanced/create_custom_transports/index.md b/_docs/tutorials/advanced/create_custom_transports/index.md index f361abd7..1fe5358d 100644 --- a/_docs/tutorials/advanced/create_custom_transports/index.md +++ b/_docs/tutorials/advanced/create_custom_transports/index.md @@ -153,7 +153,7 @@ Add member ```cpp bool eprosima::uxr::CustomEndPoint::add_member<*KIND*>(const std::string& member_name); ``` -Allows to dynamically add a new member to the endpoint definition. +This function allows to dynamically add a new member to the endpoint definition. Ir returns ``true`` if the member was correctly added, ``false`` if something went wrong (for example, if the member already exists). From 25a8921a6c36f9ba761081baa8b3b474ce63cfce Mon Sep 17 00:00:00 2001 From: Pablo Garrido Date: Mon, 1 Mar 2021 12:39:15 +0100 Subject: [PATCH 28/29] Update _docs/tutorials/advanced/create_custom_transports/index.md Co-authored-by: FranFin <58737168+FranFin@users.noreply.github.com> --- _docs/tutorials/advanced/create_custom_transports/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_docs/tutorials/advanced/create_custom_transports/index.md b/_docs/tutorials/advanced/create_custom_transports/index.md index 1fe5358d..78334f49 100644 --- a/_docs/tutorials/advanced/create_custom_transports/index.md +++ b/_docs/tutorials/advanced/create_custom_transports/index.md @@ -140,7 +140,7 @@ As in the *Client* API, four functions should be implemented. The behavior of th depending on the selected mode. ### CustomEndPoint -The `custom_endpoint` is an object of type `eprosima::uxr::CustomEndPoint` and it us in charge of handling the endpoint parameters. The *Agent*, unlike the *Client*, can receive +The `custom_endpoint` is an object of type `eprosima::uxr::CustomEndPoint` and it is in charge of handling the endpoint parameters. The *Agent*, unlike the *Client*, can receive messages from multiple *Clients* so it must be able to differentiate between them. Therefore, the `eprosima::uxr::CustomEndPoint` should be provided with information about the origin of the message in the read callback, and with information about the destination of the message in the write callback. From d7b61935a726e597d5cac48dc2d13acb6c3bf30a Mon Sep 17 00:00:00 2001 From: Pablo Garrido Date: Mon, 1 Mar 2021 12:39:21 +0100 Subject: [PATCH 29/29] Update _docs/tutorials/advanced/create_custom_transports/index.md Co-authored-by: FranFin <58737168+FranFin@users.noreply.github.com> --- _docs/tutorials/advanced/create_custom_transports/index.md | 1 + 1 file changed, 1 insertion(+) diff --git a/_docs/tutorials/advanced/create_custom_transports/index.md b/_docs/tutorials/advanced/create_custom_transports/index.md index 78334f49..7e83260c 100644 --- a/_docs/tutorials/advanced/create_custom_transports/index.md +++ b/_docs/tutorials/advanced/create_custom_transports/index.md @@ -138,6 +138,7 @@ custom_agent.start(); ``` As in the *Client* API, four functions should be implemented. The behavior of these functions is sightly different depending on the selected mode. + ### CustomEndPoint The `custom_endpoint` is an object of type `eprosima::uxr::CustomEndPoint` and it is in charge of handling the endpoint parameters. The *Agent*, unlike the *Client*, can receive