Skip to content

Commit fed0729

Browse files
hierophecthierophect
committed
Add documentation
1 parent 1cccbc7 commit fed0729

File tree

3 files changed

+154
-0
lines changed

3 files changed

+154
-0
lines changed

‎shared-bindings/rclcpy/Node.c

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,27 @@
1212
#include "py/objtype.h"
1313
#include "py/runtime.h"
1414

15+
//| class Node:
16+
//| """A ROS2 Node"""
17+
//|
18+
//| def __init__(
19+
//| self,
20+
//| node_name: str,
21+
//| *,
22+
//| namespace: str | None = None,
23+
//| ) -> None:
24+
//| """Create a Node.
25+
//|
26+
//| Creates an instance of a ROS2 Node. Nodes can be used to create other ROS
27+
//| entities like publishers or subscribers. Nodes must have a unique name, and
28+
//| may also be constructed from their class.
29+
//|
30+
//| :param str node_name: The name of the node. Must be a valid ROS 2 node name
31+
//| :param str namespace: The namespace for the node. If None, the node will be
32+
//| created in the root namespace
33+
//| """
34+
//| ...
35+
//|
1536
static mp_obj_t rclcpy_node_make_new(const mp_obj_type_t *type, size_t n_args, size_t n_kw, const mp_obj_t *all_args) {
1637
enum { ARG_node_name, ARG_namespace };
1738
static const mp_arg_t allowed_args[] = {
@@ -31,6 +52,12 @@ static mp_obj_t rclcpy_node_make_new(const mp_obj_type_t *type, size_t n_args, s
3152
return (mp_obj_t)self;
3253
}
3354

55+
//| def deinit(self) -> None:
56+
//| """Deinitializes the node and frees any hardware or remote agent resources
57+
//| used by it. Deinitialized nodes cannot be used again.
58+
//| """
59+
//| ...
60+
//|
3461
static mp_obj_t rclcpy_node_obj_deinit(mp_obj_t self_in) {
3562
rclcpy_node_obj_t *self = MP_OBJ_TO_PTR(self_in);
3663
common_hal_rclcpy_node_deinit(self);
@@ -44,6 +71,17 @@ static void check_for_deinit(rclcpy_node_obj_t *self) {
4471
}
4572
}
4673

74+
//| def create_publisher(self, topic: str) -> Publisher:
75+
//| """Create a publisher for a given topic string.
76+
//|
77+
//| Creates an instance of a ROS2 Publisher.
78+
//|
79+
//| :param str topic: The name of the topic
80+
//| :return: A new Publisher object for the specified topic
81+
//| :rtype: Publisher
82+
//| """
83+
//| ...
84+
//|
4785
static mp_obj_t rclcpy_node_create_publisher(mp_obj_t self_in, mp_obj_t topic) {
4886
rclcpy_node_obj_t *self = MP_OBJ_TO_PTR(self_in);
4987
check_for_deinit(self);
@@ -55,6 +93,14 @@ static mp_obj_t rclcpy_node_create_publisher(mp_obj_t self_in, mp_obj_t topic) {
5593
}
5694
static MP_DEFINE_CONST_FUN_OBJ_2(rclcpy_node_create_publisher_obj, rclcpy_node_create_publisher);
5795

96+
//| def get_name(self) -> str:
97+
//| """Get the name of the node.
98+
//|
99+
//| :return: The node's name
100+
//| :rtype: str
101+
//| """
102+
//| ...
103+
//|
58104
static mp_obj_t rclcpy_node_get_name(mp_obj_t self_in) {
59105
rclcpy_node_obj_t *self = MP_OBJ_TO_PTR(self_in);
60106
check_for_deinit(self);
@@ -63,6 +109,14 @@ static mp_obj_t rclcpy_node_get_name(mp_obj_t self_in) {
63109
}
64110
static MP_DEFINE_CONST_FUN_OBJ_1(rclcpy_node_get_name_obj, rclcpy_node_get_name);
65111

112+
//| def get_namespace(self) -> str:
113+
//| """Get the namespace of the node.
114+
//|
115+
//| :return: The node's namespace
116+
//| :rtype: str
117+
//| """
118+
//| ...
119+
//|
66120
static mp_obj_t rclcpy_node_get_namespace(mp_obj_t self_in) {
67121
rclcpy_node_obj_t *self = MP_OBJ_TO_PTR(self_in);
68122
check_for_deinit(self);

‎shared-bindings/rclcpy/Publisher.c

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,10 +11,28 @@
1111
#include "py/objtype.h"
1212
#include "py/runtime.h"
1313

14+
//| class Publisher:
15+
//| """A ROS2 publisher"""
16+
//|
17+
//| def __init__(self) -> None:
18+
//| """Publishers cannot be created directly.
19+
//|
20+
//| Use :meth:`Node.create_publisher` to create a publisher from a node.
21+
//|
22+
//| :raises NotImplementedError: Always, as direct instantiation is not supported
23+
//| """
24+
//| ...
25+
//|
1426
static mp_obj_t rclcpy_publisher_make_new(const mp_obj_type_t *type, size_t n_args, size_t n_kw, const mp_obj_t *all_args) {
1527
mp_raise_NotImplementedError(MP_ERROR_TEXT("Publishers can only be created from a parent node"));
1628
}
1729

30+
//| def deinit(self) -> None:
31+
//| """Deinitializes the publisher and frees any hardware or remote agent resources
32+
//| used by it. Deinitialized publishers cannot be used again.
33+
//| """
34+
//| ...
35+
//|
1836
static mp_obj_t rclcpy_publisher_obj_deinit(mp_obj_t self_in) {
1937
rclcpy_publisher_obj_t *self = MP_OBJ_TO_PTR(self_in);
2038
common_hal_rclcpy_publisher_deinit(self);
@@ -28,6 +46,14 @@ static void check_for_deinit(rclcpy_publisher_obj_t *self) {
2846
}
2947
}
3048

49+
//| def publish_int32(self, message: int) -> None:
50+
//| """Publish a 32-bit signed integer message to the topic.
51+
//|
52+
//| :param int message: The integer value to publish. Must be within the range
53+
//| of a 32-bit signed integer (-2,147,483,648 to 2,147,483,647)
54+
//| """
55+
//| ...
56+
//|
3157
static mp_obj_t rclcpy_publisher_publish_int32(mp_obj_t self_in, mp_obj_t in_msg) {
3258
rclcpy_publisher_obj_t *self = MP_OBJ_TO_PTR(self_in);
3359
check_for_deinit(self);
@@ -37,6 +63,14 @@ static mp_obj_t rclcpy_publisher_publish_int32(mp_obj_t self_in, mp_obj_t in_msg
3763
}
3864
static MP_DEFINE_CONST_FUN_OBJ_2(rclcpy_publisher_publish_int32_obj, rclcpy_publisher_publish_int32);
3965

66+
//| def get_topic_name(self) -> str:
67+
//| """Get the name of the topic this publisher publishes to.
68+
//|
69+
//| :return: The topic name as specified when the publisher was created
70+
//| :rtype: str
71+
//| """
72+
//| ...
73+
//|
4074
static mp_obj_t rclcpy_publisher_get_topic_name(mp_obj_t self_in) {
4175
rclcpy_publisher_obj_t *self = MP_OBJ_TO_PTR(self_in);
4276
check_for_deinit(self);

‎shared-bindings/rclcpy/__init__.c

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,52 @@
1313
#include "py/objstr.h"
1414
#include "py/runtime.h"
1515

16+
//| """Robot Operating System (ROS2) connectivity through micro-ROS
17+
//|
18+
//| The `rclcpy` module contains basic classes and connectivity options for
19+
//| communicating with a ROS network running on a linux machine, using the
20+
//| eProsima's `micro-ROS client API <https://micro.ros.org/>`_.
21+
//|
22+
//| The underlying micro-ROS system uses a resource-constrained middleware layer
23+
//| (XRCE-DDS) that must be connected to an agent running within ROS2 on a host
24+
//| Linux computer. The API exposed by Circuitpython aims to be close to the
25+
//| standard Python API for ROS2, `rclpy`, with minor additions to support
26+
//| connecting to this agent.
27+
//|
28+
//| Wifi must be connected before calling any `rclcpy` functions. As with
29+
//| `rclpy`, the `rclcpy.init()` function must be run before creating any ROS
30+
//| objects. Child objects, such as publishers, must be created by their parent
31+
//| objects. For example::
32+
//|
33+
//| import os, wifi, time
34+
//| import rclcpy
35+
//| wifi.radio.connect(ssid=os.getenv('CIRCUITPY_WIFI_SSID'),
36+
//| password=os.getenv('CIRCUITPY_WIFI_PASSWORD'))
37+
//| rclcpy.init("192.168.10.111","8888")
38+
//| mynode = rclcpy.Node("foo")
39+
//| mypub = mynode.create_publisher("bar")
40+
//| mypub.publish_int32(42)
41+
//| """
42+
43+
44+
//| def init(
45+
//| agent_ip: str,
46+
//| agent_port: str,
47+
//| *,
48+
//| domain_id: int = 0,
49+
//| ) -> None:
50+
//| """Initialize micro-ROS and connect to a micro-ROS agent.
51+
//|
52+
//| This function starts ROS communications and connects to the micro-ROS agent
53+
//| on a linux computer. It must be called before creating ROS objects.
54+
//|
55+
//| :param str agent_ip: The IP address of the micro-ROS agent
56+
//| :param str agent_port: The port number of the micro-ROS agent as a string
57+
//| :param int domain_id: The ROS 2 domain ID for network isolation and organization.
58+
//| Devices with the same domain ID can communicate with each other.
59+
//| """
60+
//| ...
61+
//|
1662
static mp_obj_t rclcpy_init(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) {
1763
enum { ARG_agent_ip, ARG_agent_port, ARG_domain_id};
1864
static const mp_arg_t allowed_args[] = {
@@ -31,6 +77,26 @@ static mp_obj_t rclcpy_init(size_t n_args, const mp_obj_t *pos_args, mp_map_t *k
3177
}
3278
static MP_DEFINE_CONST_FUN_OBJ_KW(rclcpy_init_obj, 2, rclcpy_init);
3379

80+
81+
//| def create_node(
82+
//| node_name: str,
83+
//| *,
84+
//| namespace: str | None = None
85+
//| ) -> Node:
86+
//| """Create a Node.
87+
//|
88+
//| Creates an instance of a ROS2 Node. Nodes can be used to create other ROS
89+
//| entities like publishers or subscribers. Nodes must have a unique name, and
90+
//| may also be constructed from their class.
91+
//|
92+
//| :param str node_name: The name of the node. Must be a valid ROS 2 node name.
93+
//| :param str namespace: The namespace for the node. If None, the node will be
94+
//| created in the root namespace.
95+
//| :return: A new Node object
96+
//| :rtype: Node
97+
//| """
98+
//| ...
99+
//|
34100
static mp_obj_t rclcpy_create_node(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) {
35101
enum { ARG_node_name, ARG_namespace };
36102
static const mp_arg_t allowed_args[] = {

0 commit comments

Comments
 (0)