You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Optmized documentation for new application developers
Fix#664
README.md
* Added **install** section with npm install directions
* Tweaked rclnodejs-ros2 version compatibility table
* Moved "Build from Scratch" section lower in document
* Removed and reduced wordiness of typescript section
npmjs-readme.md
* Replaced link to clnodejs-ros2 version compatibility table with the
table content
* Added link to github project ./example folder
* Removed some wordy typescript content
`rclnodejs` is a Node.js client for the Robot Operating System (ROS 2). It provides a simple and easy JavaScript API for ROS 2 programming. TypeScript declarations are included to support use of rclnodejs in TypeScript projects.
9
9
10
-
If you want to select a stable release of ROS 2.0 as your platform, please check the table below.
10
+
Here's an example for how to create a ROS 2 node that publishes a string message in a few lines of JavaScript.
*[Node.js](https://nodejs.org/en/) version between 8.12 - 12.x.
26
+
27
+
**ROS 2 SDK**
28
+
* See the ROS 2 SDK [Installation Guide](https://index.ros.org/doc/ros2/Installation/) for details.
29
+
**** DON'T FORGET TO [SOURCE THE ROS 2 STARTUP FILES](https://index.ros.org/doc/ros2/Tutorials/Configuring-ROS2-Environment/#source-the-setup-files)***
30
+
31
+
## Install rclnodejs
32
+
33
+
Install the rclnodejs version that is compatible with your version of ROS 2 (see table below).
34
+
35
+
Run the following command for the most current version of rclnodejs
-**Note:** to install rclnodejs from GitHub: add `"rclnodejs":"RobotWebTools/rclnodejs#<branch>"` to your `package.json` depdendency section.
58
+
59
+
## API Documentation
60
+
61
+
The API documentation is generated by `jsdoc`. To create a local copy run `npm run docs`. Alternatively you can use the prebuilt api documentation found in the `docs/` folder or view the [on-line version](http://robotwebtools.org/rclnodejs/docs/index.html) in your browser.
62
+
63
+
## Using TypeScript
64
+
65
+
TypeScript declaration files (\*.d.ts) are included to support developers that wish to use rclnodejs in TypeScript projects.
66
+
67
+
In your node project, in addition to installing the rclnodejs package, you will need to install the TypeScript compiler and node typings.
68
+
69
+
```
70
+
npm install typescript @types/node -D
71
+
```
72
+
73
+
Your tsconfig.json file should include the following compiler options:
74
+
75
+
```json
76
+
{
77
+
"compilerOptions": {
78
+
"module": "commonjs",
79
+
"moduleResolution": "node",
80
+
"target": "es6"
81
+
// your additional options here
82
+
}
83
+
}
84
+
```
85
+
86
+
Here's a simple example implemented in TypeScript.
- Verify that you are using a compatible version of node between 8.12 - 12.99: run `node -v` for your node version info.
98
+
The benefits of using TypeScript become evident when working with more complex use-cases. The ROS 2 messages are defined in the `types/interfaces.d.ts` module. This module is updated as part of the `generate_messages` process. Here's a trivial example of working with a String msg.
22
99
23
-
- Install from npmjs: run `npm i rclnodejs@<version>` to install a specific version.
100
+
```
101
+
const msg: rclnodejs.std_msgs.msg.String = {
102
+
data: 'hello ROS2 from rclnodejs'
103
+
}
104
+
```
24
105
25
-
- Install from GitHub: add `"rclnodejs":"RobotWebTools/rclnodejs#<branch>"` to your `package.json`.
26
106
27
107
## Build from Scratch
28
108
29
109
### Get ready for ROS 2
30
110
31
-
1.Install ROS 2.0 from binary package.
111
+
1.Install ROS 2 from binary package.
32
112
33
-
ROS 2.0 is a cross-platform system, which covers Linux, macOS and Windows, and the `rclnodejs` module is developed against the [`master`](https://github.com/ros2/ros2/blob/master/ros2.repos) branch of ROS 2.0. You can download the latest binary packages from [ROS 2.0 build farm](http://ci.ros2.org/view/packaging/) and follow the instructions of [Linux](https://index.ros.org/doc/ros2/Installation/Linux-Install-Binary/)/[macOS](https://index.ros.org/doc/ros2/Installation/OSX-Install-Binary/)/[Windows](https://index.ros.org/doc/ros2/Installation/Windows-Install-Binary/) to setup the environment (If you want to run your apps on a stable release of ROS 2.0, e.g. crystal-clemmys, please see the section `Running on Stable Release of ROS 2.0`).
113
+
ROS 2 is a cross-platform system, which covers Linux, macOS and Windows, and the `rclnodejs` module is developed against the [`master`](https://github.com/ros2/ros2/blob/master/ros2.repos) branch of ROS 2. You can download the latest binary packages from [ROS 2 build farm](http://ci.ros2.org/view/packaging/) and follow the instructions of [Linux](https://index.ros.org/doc/ros2/Installation/Linux-Install-Binary/)/[macOS](https://index.ros.org/doc/ros2/Installation/OSX-Install-Binary/)/[Windows](https://index.ros.org/doc/ros2/Installation/Windows-Install-Binary/) to setup the environment (If you want to run your apps on a stable release of ROS 2, e.g. crystal-clemmys, please see the section `Running on Stable Release of ROS 2).
34
114
35
-
2.Build ROS 2.0 from scratch.
115
+
2.Build ROS 2 from scratch.
36
116
37
-
Alternatively, you can build ROS 2.0 from scratch. Please select the platform you want to work on, then reference the instructions of [Linux](https://index.ros.org/doc/ros2/Installation/Linux-Development-Setup/)/[macOS](https://index.ros.org/doc/ros2/Installation/OSX-Development-Setup/)/[Windows](https://index.ros.org/doc/ros2/Installation/Windows-Development-Setup/) to build ROS 2.0 (please build wiht flag `--merge-install`).
117
+
Alternatively, you can build ROS 2 from scratch. Please select the platform you want to work on, then reference the instructions of [Linux](https://index.ros.org/doc/ros2/Installation/Linux-Development-Setup/)/[macOS](https://index.ros.org/doc/ros2/Installation/OSX-Development-Setup/)/[Windows](https://index.ros.org/doc/ros2/Installation/Windows-Development-Setup/) to build ROS 2 (please build wiht flag `--merge-install`).
Browse the JavaScript programs in the `example` folder to learn how to create and work with `timers, subscriptions, publishers, clients, services, timers,` and `nodes`.
129
209
130
-
## API Specification
131
-
132
-
The API spec is generated by `jsdoc`. To create a local copy run `npm run docs`. Alternatively you can use the prebuilt api documentation found in the `docs` folder or view the [on-line version](http://robotwebtools.org/rclnodejs/docs/index.html) in your browser.
133
-
134
-
## TypeScript Support
135
-
136
-
Type declaration files (\*.d.ts) are included to support developers that wish to use rclnodejs in TypeScript projects.
137
-
138
-
In your node project, in addition to installing the rclnodejs package, you will need to install the TypeScript compiler and node typings.
139
-
140
-
```
141
-
npm install typescript @types/node -D
142
-
```
143
-
144
-
Your tsconfig.json file should include the following compiler options:
145
-
146
-
```json
147
-
{
148
-
"compilerOptions": {
149
-
"module": "commonjs",
150
-
"moduleResolution": "node",
151
-
"target": "es6"
152
-
// your additional options here
153
-
}
154
-
}
155
-
```
156
-
157
-
Here's a simple example implemented in TypeScript.
publisher.publish(`Hello ROS 2.0 from rclnodejs`);
165
-
rclnodejs.spin(node);
166
-
});
167
-
```
168
-
169
-
The benefits of using TypeScript become evident when working with more complex messages. The ROS2 messages are defined in the interfaces.d.ts module. This module is updated as part of the generate_messages process. Here's a trivial example of working with a String msg.
170
-
171
-
```
172
-
const msg: rclnodejs.std_msgs.msg.String = {
173
-
data: 'hello ROS2 from rclnodejs'
174
-
}
175
-
```
176
-
177
-
Smart TypeScript tools such as Visual Studio Code and the CodeMix plugin for Eclipse will help you learn the rclnodejs api and identify issues while coding rather than at runtime.
178
-
179
210
## Troubleshooting
180
211
181
212
### Maximum call stack size exceeded error when running in Jest
`rclnodejs` is a Node.js client for the Robot Operating System (ROS) v2.0. It provides a simple and easy JavaScript API for ROS 2.0 programming. TypeScript declarations are included to support use of rclnodejs in TypeScript projects.
3
+
`rclnodejs` is a Node.js client for the Robot Operating System (ROS 2). It provides a simple and easy JavaScript API for ROS 2 programming. TypeScript declarations are included to support use of rclnodejs in TypeScript projects.
4
4
5
-
The following JavaScript example demonstrates how to create a ROS 2.0 node and then publish a string message in only 6 lines of code.
5
+
Here's an example for how to create a ROS 2 node that publishes a string message in a few lines of JavaScript.
publisher.publish(`Hello ROS 2.0 from rclnodejs`);
12
+
publisher.publish(`Hello ROS 2 from rclnodejs`);
13
13
rclnodejs.spin(node);
14
14
});
15
15
```
16
16
17
-
## Install ROS 2.0
17
+
## Prerequisites
18
18
19
-
Before install rclnodejs, make sure ROS 2.0 is installed first. Read and follow the [Installation Guide](https://index.ros.org/doc/ros2/Installation/) to install ROS 2.0
19
+
**Node.js**
20
+
*[Node.js](https://nodejs.org/en/) version between 8.12 - 12.x.
21
+
22
+
**ROS 2 SDK**
23
+
* See the ROS 2 SDK [Installation Guide](https://index.ros.org/doc/ros2/Installation/) for details.
24
+
**** DON'T FORGET TO [SOURCE THE ROS 2 STARTUP FILES](https://index.ros.org/doc/ros2/Tutorials/Configuring-ROS2-Environment/#source-the-setup-files)***
20
25
21
26
## Install rclnodejs
22
27
23
-
After ROS 2.0 is installed, run the following command
28
+
Install the rclnodejs version that is compatible with your installed version of ROS 2 (see table below).
29
+
30
+
Run the following command for the most current version of rclnodejs
publisher.publish(`Hello ROS 2.0 from rclnodejs`);
149
+
publisher.publish(`Hello ROS 2 from rclnodejs`);
130
150
rclnodejs.spin(node);
131
151
});
132
152
```
133
153
134
-
In this example you may notice that other than the `import` statement the code is virtually identical to the JavaScript version. Where the benefits of using TypeScript kick in is when using smart coding tools such as Visual Studio Code or the CodeMix plugin for Eclipse. These productivity tools use the rclnodejs type declaration files to help you learn the api and code with it more accurately and quickly.
135
-
136
-
Type aliases are provided for the ROS2 messages in the types/interfaces.d.ts file. To use a message type alias follow the naming pattern <pkg_name>.[msg|srv].<type>, e.g., sensor_msgs.msg.LaserScan or the std_msgs.msg.String as shown below.
154
+
Type-aliases for the ROS2 messages can be found in the `types/interfaces.d.ts` file. To use a message type-alias follow the naming pattern <pkg_name>.[msg|srv].<type>, e.g., sensor_msgs.msg.LaserScan or the std_msgs.msg.String as shown below.
137
155
```
138
156
const msg: rclnodejs.std_msgs.msg.String = {
139
157
data: 'hello ROS2 from rclnodejs'
140
158
}
141
159
```
142
160
**Note** that the interface.d.ts file is updated each time the generate_messages.js script is run.
143
161
144
-
While the code snippet above is a trivial message example, when working with more complex message types such as sensor data, developers can benefit from typing information to help detect issues earlier in the develpment cycle.
0 commit comments