# WxJava **Repository Path**: williamjamskayi/weixin-java-tools ## Basic Information - **Project Name**: WxJava - **Description**: 微信开发 Java SDK，支持微信支付、开放平台、公众号、视频号、企业微信、小程序等的后端开发，记得关注公众号及时接受版本更新信息，以及加入微信群进行深入讨论 - **Primary Language**: Java - **License**: Apache-2.0 - **Default Branch**: develop - **Homepage**: https://www.oschina.net/p/weixin-java-tools-new - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 5873 - **Created**: 2024-09-08 - **Last Updated**: 2024-10-11 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README ## WxJava - 微信开发 Java SDK [![码云Gitee](https://gitee.com/binary/weixin-java-tools/badge/star.svg?theme=blue)](https://gitee.com/binary/weixin-java-tools) [![Github](https://img.shields.io/github/stars/Wechat-Group/WxJava?logo=github&style=flat)](https://github.com/Wechat-Group/WxJava) [![GitHub release](https://img.shields.io/github/release/Wechat-Group/WxJava.svg)](https://github.com/Wechat-Group/WxJava/releases) [![Maven Central](https://img.shields.io/maven-central/v/com.github.binarywang/wx-java.svg)](http://mvnrepository.com/artifact/com.github.binarywang/wx-java) [![Build Status](https://img.shields.io/circleci/project/github/Wechat-Group/WxJava/develop.svg?sanitize=true)](https://circleci.com/gh/Wechat-Group/WxJava/tree/develop) [![使用IntelliJ IDEA开发维护](https://img.shields.io/badge/IntelliJ%20IDEA-支持-blue.svg)](https://www.jetbrains.com/?from=WxJava-weixin-java-tools) [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) #### 微信`Java`开发工具包，支持包括微信支付、开放平台、公众号、企业微信、视频号、小程序等微信功能模块的后端开发。

特别赞助

### 重要信息 1. 项目合作洽谈请联系微信`binary0000`（在微信里自行搜索并添加好友，请注明来意，如有关于SDK问题需讨论请参考下文入群讨论，不要加此微信）。 2. **2023-12-28 发布 [【4.6.0正式版】](https://mp.weixin.qq.com/s/9Hhc_8w-v7ogS_TEAsqfAg)**！ 3. 贡献源码可以参考视频：[【贡献源码全过程（上集）】](https://mp.weixin.qq.com/s/3xUZSATWwHR_gZZm207h7Q)、[【贡献源码全过程（下集）】](https://mp.weixin.qq.com/s/nyzJwVVoYSJ4hSbwyvTx9A) ，友情提供：[程序员小山与Bug](https://space.bilibili.com/473631007) 4. 新手重要提示：本项目仅是一个SDK开发工具包，未提供Web实现，建议使用 `maven` 或 `gradle` 引用本项目即可使用本SDK提供的各种功能，详情可参考 **[【Demo项目】](demo.md)** 或本项目中的部分单元测试代码； 5. 微信开发新手请务必阅读【开发文档】（[Gitee Wiki](https://gitee.com/binary/weixin-java-tools/wikis/Home) 或者 [Github Wiki](https://github.com/Wechat-Group/WxJava/wiki)）的常见问题部分，可以少走很多弯路，节省不少时间。 6. 技术交流群：想获得QQ群/微信群/钉钉企业群等信息的同学，请使用微信扫描上面的微信公众号二维码关注 `WxJava` 后点击相关菜单即可获取加入方式，同时也可以在微信中搜索 `weixin-java-tools` 或 `WxJava` 后选择正确的公众号进行关注，该公众号会及时通知SDK相关更新信息，并不定期分享微信Java开发相关技术知识； 7. 钉钉技术交流群：`32206329`（技术交流2群）, `30294972`（技术交流1群，目前已满），`35724728`（通知群，实时通知Github项目变更记录）。 8. 微信开发新手或者Java开发新手在群内提问或新开Issue提问前，请先阅读[【提问的智慧】](https://github.com/ryanhanwu/How-To-Ask-Questions-The-Smart-Way/blob/master/README-zh_CN.md)，并确保已查阅过 [【开发文档Wiki】](https://github.com/wechat-group/WxJava/wiki) ，避免浪费大家的宝贵时间； 9. 寻求帮助时需贴代码或大长串异常信息的，请利用 http://paste.ubuntu.com -------------------------------- ### 其他说明 1. **阅读源码的同学请注意，本SDK为简化代码编译时加入了`lombok`支持，如果不了解`lombok`的话，请先学习下相关知识，比如可以阅读[此文章](https://mp.weixin.qq.com/s/cUc-bUcprycADfNepnSwZQ)；** 2. 如有新功能需求，发现BUG，或者由于微信官方接口调整导致的代码问题，可以直接在[【Issues】](https://github.com/Wechat-Group/WxJava/issues)页提出issue，便于讨论追踪问题； 3. 如果需要贡献代码，请务必在提交PR之前先仔细阅读[【代码贡献指南】](CONTRIBUTING.md)，谢谢理解配合； 4. 目前本`SDK`最新版本要求的`JDK`最低版本是`8`，使用`7`的同学可以使用`WxJava` `3.8.0`及以前版本，而还在使用`JDK`6的用户请参考[【此项目】]( https://github.com/binarywang/weixin-java-tools-for-jdk6) ，而其他更早的JDK版本则需要自己改造实现。 5. [本项目在开源中国的页面](https://www.oschina.net/p/weixin-java-tools-new)，欢迎大家积极留言评分 🙂 6. SDK开发文档请查阅 [【开发文档Wiki】](https://github.com/wechat-group/WxJava/wiki)，部分文档可能未能及时更新，如有发现，可以及时上报或者自行修改。 7. **如果本开发工具包对您有所帮助，欢迎对我们的努力进行肯定，可以直接前往[【托管于码云的项目首页】](http://gitee.com/binary/weixin-java-tools)，在页尾部分找到“捐助”按钮进行打赏，多多益善 😄。非常感谢各位打赏和捐助的同学！** 8. 各个模块的Javadoc可以在线查看：[weixin-java-miniapp](http://binary.ac.cn/weixin-java-miniapp-javadoc/)、[weixin-java-pay](http://binary.ac.cn/weixin-java-pay-javadoc/)、[weixin-java-mp](http://binary.ac.cn/weixin-java-mp-javadoc/)、[weixin-java-common](http://binary.ac.cn/weixin-java-common-javadoc/)、[weixin-java-cp](http://binary.ac.cn/weixin-java-cp-javadoc/)、[weixin-java-open](http://binary.ac.cn/weixin-java-open-javadoc/) 9. 本SDK项目在以下代码托管网站同步更新: * 码云：https://gitee.com/binary/weixin-java-tools * GitHub：https://github.com/wechat-group/WxJava --------------------------------- ### Maven 引用方式注意：最新版本（包括测试版）为 [![Maven Central](https://img.shields.io/maven-central/v/com.github.binarywang/wx-java.svg)](http://mvnrepository.com/artifact/com.github.binarywang/wx-java)，以下为最新正式版。 ```xml com.github.binarywang （不同模块参考下文） 4.6.0 ``` - 微信小程序：`weixin-java-miniapp` - 微信支付：`weixin-java-pay` - 微信开放平台：`weixin-java-open` - 公众号（包括订阅号和服务号）：`weixin-java-mp` - 企业号/企业微信：`weixin-java-cp` --------------------------------- ### 版本说明

点此展开查看

1. 本项目定为大约每两个月发布一次正式版（同时 `develop` 分支代码合并进入 `release` 分支），版本号格式为 `X.X.0`（如`2.1.0`，`2.2.0`等），遇到重大问题需修复会及时提交新版本，欢迎大家随时提交Pull Request； 2. BUG修复和新特性一般会先发布成小版本作为临时测试版本（如`3.6.8.B`，即尾号不为0，并添加B，以区别于正式版），代码仅存在于 `develop` 分支中； 3. 目前最新版本号为 [![Maven Central](https://img.shields.io/maven-central/v/com.github.binarywang/wx-java.svg)](http://mvnrepository.com/artifact/com.github.binarywang/wx-java) ，也可以通过访问链接 [【微信支付】](http://search.maven.org/#search%7Cgav%7C1%7Cg%3A%22com.github.binarywang%22%20AND%20a%3A%22weixin-java-pay%22) 、[【微信小程序】](http://search.maven.org/#search%7Cgav%7C1%7Cg%3A%22com.github.binarywang%22%20AND%20a%3A%22weixin-java-miniapp%22) 、[【公众号】](http://search.maven.org/#search%7Cgav%7C1%7Cg%3A%22com.github.binarywang%22%20AND%20a%3A%22weixin-java-mp%22) 、[【企业微信】](http://search.maven.org/#search%7Cgav%7C1%7Cg%3A%22com.github.binarywang%22%20AND%20a%3A%22weixin-java-cp%22)、[【开放平台】](http://search.maven.org/#search%7Cgav%7C1%7Cg%3A%22com.github.binarywang%22%20AND%20a%3A%22weixin-java-open%22) 分别查看所有最新的版本。

---------------------------------- ### 应用案例完整案例登记列表，请[【访问这里】](https://github.com/Wechat-Group/weixin-java-tools/issues/729)查看，欢迎登记更多的案例。以下为节选的部分案例： #### 开源项目： - 基于微信公众号的签到、抽奖、发送弹幕程序：https://github.com/workcheng/weiya - Jeepay 支付系统：https://gitee.com/jeequan/jeepay - 微同商城：https://gitee.com/fuyang_lipengjun/platform - 微信点餐系统：https://github.com/sqmax/springboot-project - 专注批量推送的小而美的工具：https://github.com/rememberber/WePush - yshop意象商城系统：https://gitee.com/guchengwuyue/yshopmall - wx-manage（微信公众号管理项目）：https://github.com/niefy/wx-manage - 基于若依开发的微信公众号管理系统：https://gitee.com/joolun/JooLun-wx - SAAS微信小程序电商：https://gitee.com/wei-it/weiit-saas - mall4j 电商商城系统：https://gitee.com/gz-yami/mall4j #### 小程序： - （京东）友家铺子，友家铺子店长版，京粉精选 - [喵星人贴吧助手(扫码关注)](http://p98ahz3tg.bkt.clouddn.com/miniappqrcode.jpg) - 树懒揽书+ - 广廉快线，鹏城巴士等 - 当燃挑战、sportlight轻灵运动 - 360考试宝典 - 民医台 - 来一团商家版 - 史必达（史丹利） - 嘀嗒云印 - 维沃吼吼 - 王朝社区（比亚迪新能源社区） - 极吼吼手机上门回收换新 - 未来信封 - 5G惠享 - 生菜wordpress转小程序 - 丽日购 #### 公众号： - 中国电信上海网厅（sh_189） - E答平台 - 宁夏生鲜365 - 通服货滴 - 神龙养车 - 沃音乐商务智能 - 光环云社群 - 手机排队 - [全民约跑健身便利店](http://www.oneminsport.com/) - 民医台 - YshopMall - 好行景区直通车以及全国40多个公众号 - 我奥篮球公众号 - 未来信封官微 - 银川智云问诊 - 5G惠享 #### 企业微信： - HTC企业微信 - 掌上史丹利 - 药店益 #### 其他： - 高善人力资源 - 小猪餐餐 - 餐饮系统 - 微信公众号管理系统：http://demo.joolun.com - 锐捷网络：Saleslink ---------------------------------- ### 贡献者列表特别感谢参与贡献的所有同学，所有贡献者列表请在[此处](https://github.com/Wechat-Group/WxJava/graphs/contributors)查看，欢迎大家继续踊跃贡献代码！

点击此处展开查看贡献次数最多的几位小伙伴

1. [chanjarster (Daniel Qian)](https://github.com/chanjarster) 2. [binarywang (Binary Wang)](https://github.com/binarywang) 3. [007gzs](https://github.com/007gzs) 4. [Silloy](https://github.com/silloy) 5. [mgcnrx11](https://github.com/mgcnrx11) 6. [0katekate0 (Wang_Wong)](https://github.com/0katekate0) 7. [yuanqixun](https://github.com/yuanqixun) 8. [kakotor](https://github.com/kakotor) 9. [aimilin6688 (Jonk)](https://github.com/aimilin6688) 10. [lkqm (Mario Luo)](https://github.com/lkqm) 11. [kareanyi (MillerLin)](https://github.com/kareanyi) 12. [Bincent (Hongbin.hsu)](https://gitee.com/bincent)

### GitHub Stargazers over time [![Stargazers over time](https://starchart.cc/Wechat-Group/WxJava.svg)](https://starchart.cc/Wechat-Group/WxJava) # Node-RED ROS 2 Plugin [![License: MIT](https://img.shields.io/github/license/ramp-eu/TTE.project1.svg)](https://opensource.org/licenses/MIT) This project is part of [DIH^2](http://www.dih-squared.eu/). The main goal is provide [Node-RED](https://nodered.org/docs/) interoperability with [ROS2](https://docs.ros.org/) and [FIWARE](https://fiware-orion.readthedocs.io/en/master/). The plugin introduces in the Node-RED palette new nodes dealing with: ### Type definition In order to transmit information it is necessary to precisely define the composition of the data delivered. Node-RED approach is based on [JSON](https://www.json.org/json-en.html) which is versatile and user friendly but cannot be used to interoperate with industrial protocols that require language-independent type Description. In order to provide this interoperability ROS2 introduced [IDL](https://www.omg.org/spec/IDL/4.2/About-IDL). Which is a data type and interfaces descriptive language customary in industrial applications. The new nodes make both: IDL type descriptions and well known ROS2 types available. ### ROS2 Publisher-Subscriber interface Publisher and Subscriber nodes are provided to directly access its ROS2 counterparts. Different topics and QoS can be selected. Also a global configuration node allows to select the ROS domain to enforce. ### FIWARE Context Broker Publisher-Subscriber interface The Context Broker doesn't provide a Publisher-Subscriber interface (works more like a database) but a translation can be easily performed if: - Entities are understood as topics. - Creating or setting an entry is understood as publishing. - Notification callbacks on an entity are understood as subscribtion callbacks. ## Contents - [Background](#background) - [Install](#install) - [Usage](#usage) + [ROS2 nodes usage](#ros2-nodes-usage) + [ROS2 Examples](#ros2-examples) + [FIWARE nodes usage](#fiware-nodes-usage) + [FIWARE Examples](#fiware-examples) ## Background The interoperability between the plugin and the ROS2 and FIWARE Broker environments is achieved using [WebSocket](https://websockets.spec.whatwg.org//) bridges to them. This was the natural choice given that Node-RED relies on WebSocket for front-end/back-end communication. These bridges are generated using [Integration-Service](https://integration-service.docs.eprosima.com/en/latest/) an [eProsima](https://www.eprosima.com/) open-source tool. Using Integration-Service directly from the plugin was possible, but it was considered a better choice to create another Node.js library ([is-web-api](https://github.com/eProsima/is-web-api), to abstract the bridge operation. This way: + The plugin can rely on any other bridge technology. + Development is simplified by enforcing separation of concerns. + Any other Node.js project (besides the plugin) can profit from the bridge library. ## Install A [Dockerfile](./docker/Dockerfile) is provided to exemplify the set up on an argument provided ROS2 distro. ### Dependencies Some of the following installation steps can be skipped if the target system already fulfils some of the requirements: 1. ROS2 installation. Follow the [official ROS2 installation guide](https://docs.ros.org/en/humble/Installation.html) for the distro of choice. The Dockerfile is based on a ROS2 image, so this is not exemplified. 1. Install Node.js. The usual OS package managers (like `apt` on Ubuntu or `winget/chocolatey` on windows) provide it. An exhaustive list is available [here](https://nodejs.org/en/download/package-manager). Some package managers constrain the user to a specific version of Node.js. The Node.js [site](https://nodejs.org/en/download) hints on how to install specific versions. For example, in `apt` is possible to add via location configuration file a new remote repository where all Node.js versions are available. This is the strategy that the Dockerfile uses: ```bash $ curl -sL https://deb.nodesource.com/setup_14.x -o nodesource_setup.sh $ chmod +x nodesource_setup.sh && sudo sh -c ./nodesource_setup.sh $ sudo apt-get install -y nodejs ``` 1. Install Node-RED. Follow the [official Node-RED installation guide](https://nodered.org/docs/getting-started/local). The Dockerfile favors the easiest procedure which relies on `npm` (default Node.js package manager) which is available after Node.js installation step: ```bash $ npm install -g node-red ``` 1. Install Integration-Service. Follow the [Integration-Service installation manual](https://integration-service.docs.eprosima.com/en/latest/installation_manual/installation_manual.html#installation-manual). This is exemplified in the Dockerfile, basically it is build from sources downloaded from github. Dependencies associated with the build and bridge environments are required: ```bash $ apt-get update $ apt-get install -y libyaml-cpp-dev libboost-program-options-dev libwebsocketpp-dev \ libboost-system-dev libboost-dev libssl-dev libcurlpp-dev \ libasio-dev libcurl4-openssl-dev git $ mkdir -p /is_ws/src && cd "$_" $ git clone https://github.com/eProsima/Integration-Service.git is $ git clone https://github.com/eProsima/WebSocket-SH.git $ git clone https://github.com/eProsima/ROS2-SH.git $ git clone https://github.com/eProsima/FIWARE-SH.git $ . /opt/ros/humble/setup.sh # customize the ROS2 distro: foxy, galactic, humble ... $ colcon build --cmake-args -DIS_ROS2_SH_MODE=DYNAMIC --install-base /opt/is ``` Note that it uses the ROS2 build tool: [colcon](https://colcon.readthedocs.io) As ROS2 it is necessary to source and [overlay](https://colcon.readthedocs.io/en/released/developer/environment.html). In order to simplify sourcing `/opt/is` was chosen as deployment dir. The overlay can be then sourced as: ```bash $ . /opt/is/setup.bash ``` It will automatically load the ROS2 overlay too. After the overlay is sourced it must be possible to access the integration-service help as: ```bash $ integration-service --help ``` ### Plugin installation Once all the dependencies are available we can deploy the plugin via npm: + From npm repo: ```bash $ npm install -g node-red-ros2-plugin ``` + From sources. `npm` allows direct deployment from github repo: ```bash $ npm install -g https://github.com/eProsima/node-red-ros2-plugin ``` Or, as in the Dockerfile, from a local sources directory. The docker favors this approach to allow tampering with the sources. ```bash $ git clone https://github.com/eProsima/node-red-ros2-plugin.git plugin_sources $ npm install -g ./plugin_sources ``` ## Usage In order to test the plugin there are two options: follow the installation steps [above](#install) or run the test container provided [here](./docker/README.md). ### Node-RED palette The main concepts associated with Node-RED operation are explained [here](https://nodered.org/docs/user-guide/concepts). The plugin nodes are displayed on the Node-RED palette as shown in the image. From there, they can be dragged into the workspace. ![Palette layout](./docs/palette.jpg) The palette is the pane on the left where all available nodes are classified by sections. Plugin ones appear under `ROS2` and `FIWARE` (figure's red frame). The worksplace is the central pane where different flows are associated to the upper tabs. > **_Note:_** the text that labels the node, changes from palette to workspace, and may change depending on the node configuration. ### Definining a type In order the publish or subscribe data we need first to specify the associated type. The plugin provides two options: #### Choosing a predefined ROS2 type

	This node represents a specific ROS2 Builtin Type. Once in the workspace, its set up dialog can be opened by doble clicking over it.
	The dialog provides a Package drop-down control where all ROS2 msg packages are listed. Once a package is selected the Message drop-down control allows selection of a package specific message. In this example the package selected is `geometry_msgs`. From this package the `Point` message is selected.
	Once the dialog set up is saved, the node label changes to highligh the selected type in a `package/message` pattern.

#### Defining a new type via IDL

	This node represents a type defined by means of an IDL. IDL is a language that allows unambiguous specification of the interfaces that may be used to define the data types.
	The dialog provides an edit box where the desired IDL can be introduced Note that in order to use the type in ROS2 it must follow several conventions: There must be an outer module which should match the message package name. There must be an inner module called `msg`. The type name must follow PascalCase convention. By default a dummy message that follows the above guidelines is provided.
	Once the dialog set up is saved, the node label changes to highligh the selected type in a `package/message` pattern.

#### Injecting a type instance into the pipeline Node-RED pipelines start in *source nodes*. The most popular one is the [inject node](https://nodered.org/docs/user-guide/nodes#inject) which requires the user to manually defined each field associated to the type. In order to simplify this a specific node is introduced:

This node mimics the inject node behaviour but automatically populates the input dialog with the fields associated with any *type node* linked to it. For example, if we wire together a `ROS Inject` and a `ROS Type` or `IDL Type` nodes as shown in the figure:

The associated dialogs are populated with the linked type fields and types. ### ROS2 nodes usage In order to interact with a ROS2 environment we must specify the same [domain id](https://docs.ros.org/en/humble/Concepts/About-Domain-ID.html) in use for that environment. The *domain id* is a number in the range `[0, 166]` that provides isolation for ROS2 nodes. It defaults to 0 and its main advantage is reduce the incomming traffic for each ROS2 node, discharging them and speeding things up. Another key concepts in the ROS2 environment are: - [topic](https://docs.ros.org/en/humble/Tutorials/Beginner-CLI-Tools/Understanding-ROS2-Topics/Understanding-ROS2-Topics.html) one. A *topic* is a text string ROS2 nodes use to notify all other nodes in which data they are interested. When a ROS2 node wants to send or receive data it must specify: + Which type is the data they want receive. For example the `geometry_msgs/Pose` we introduced [above](#choosing-a-predefined-ros2-type). + Topic associated with the data. For example `/marker_pose`, but in ROS2 topics are often *decorated* using namespaces to simplify identification, as in `/eProsima/buildings/E3g1/room/F2h3/marker/4Rg1/pose`. - [Quality of Service (QoS)](https://docs.ros.org/en/humble/Concepts/About-Quality-of-Service-Settings.html). Those are policies that allow fine tunning of the communication between nodes. For example: + *History QoS* allows to discard messages if only the most recent one is meaningful for our purposes. + *Reliable QoS* enforces message reception by resending it until the receiver acknowledges it. + *Durability QoS* assures messages published before the receiver node creation would be delivered. > **_Note:_** ROS2 nodes can only communicate if their respective QoS are compatible. Information on QoS compatibility is available [here](https://docs.ros.org/en/humble/Concepts/About-Quality-of-Service-Settings.html#qos-compatibilities). #### ROS2 configuration node A [Node-RED config node](https://nodered.org/docs/user-guide/concepts#config-node) is provided to set up the domain ID, which is a global selection: ![ROS Config Node](./docs/ROS2ConfigNode.jpg) > **_Note:_** The ROS2 default domain value is 0 #### ROS2 Publisher

	This node represents a ROS2 publisher. It is able to publish messages on a specific topic with specific QoS
	The dialog provides controls to configure: Topic Note that the backslash `/` typical of ROS2 topics is not necessary Domain ID Selected globally via the configuration node explained above QoS The `+add` button at the bottom adds new combo-boxes to the control where the available options for each policy can be selected

#### ROS2 Subscriber

	This node represents a ROS2 subscriber. It is able to subscribe on a specific topic and receive all messages published for it.
	The dialog provides controls to configure: Topic Note that the backslash `/` typical of ROS2 topics is not necessary Domain ID Selected globally via the configuration node explained above QoS The `+add` button at the bottom adds new combo-boxes to the control where the available options for each policy can be selected

### ROS2 Examples #### ROS2 Basic Publication Example Let's show how to use a custom type. 1. Launch docker compose as explained [here](./docker/README.md). 1. Create and wire the following nodes: + An `IDL Type` node. Open the associated dialog and introduce the following idl: ```c module custom_msgs { module msg { struct Message { string text; uint64 value; }; }; }; ``` + A `ROS Publisher` node. Open the associated dialog and set up the publisher: `Topic` : hope `Domain` : 42 + A `ROS Inject` node. Open the associated dialog and fill in the fields: `text` : Hello World! `value` : 42 1. Deploy the flow pressing the corresponding button. Once deployed, the custom type has been registered in the ROS2 distro. 1. Let's launch a subscriber from the [ROS2 cli](https://docs.ros.org/en/humble/Tutorials/Beginner-CLI-Tools/Understanding-ROS2-Topics/Understanding-ROS2-Topics.html#id7). ```bash $ docker exec -ti --env ROS_DOMAIN_ID=42 docker-visual-ros-1 /ros_entrypoint.sh ros2 topic echo /hope custom_msgs/msg/Message ``` 1. Now click on the inject node button within the editor and see how the terminal receives the data. > **_Note:_** In the example the ROS2 domain value selected is 42, different from the default value of 0. ![ROS2 Publisher](./docs/ROS2Publisher.gif) #### ROS2 Basic Subscription Example In this case, a builtin ROS2 type (`geometry_msgs/Point`) will be used. 1. Launch docker compose as explained [here](./docker/README.md). 1. Create and wire the following nodes: + A `ROS2 Type` node. Open the associated dialog and select: `Package` : geometry_msgs `Message` : Point + A `ROS2 Subscriber` node. Open the associated dialog and set up the subscriber: `Topic` : hope `Domain` : 17 + A `debug` node from the `common` palette section. Open the associated dialog and set it up to show the x coordinate of the point: `Output` : `msg.x` 1. Deploy the flow pressing the corresponding button. 1. Publish a message on that topic from the ROS2 cli. In this example we launch a new container connected to the same network using the standard `ros:humble` image. ```bash $ docker run --rm -ti --env ROS_DOMAIN_ID=17 --network docker_visualros ros:humble \ ros2 topic pub /hope geometry_msgs/msg/Point "{ x: 42, y: 0, z: 0 }" ``` ![turtlesim](./docs/ROS2Subscriber.gif) #### ROS2 Mandatory Turtlesim Example [Turtlesim](https://docs.ros.org/en/humble/Tutorials/Beginner-CLI-Tools/Introducing-Turtlesim/Introducing-Turtlesim.html) is an *ad hoc* package that ROS2 provides as GUI node example. ##### Set up Unlike the previous examples turtlesim cannot work on terminal mode. There are several ways to workaround this: 1. Run GUI application in a docker container as shown [here](https://www.howtogeek.com/devops/how-to-run-gui-applications-in-a-docker-container/). 1. Share the container network stack with the host. 1. Run Node-RED backend directly in your host (see [installation steps](#install)). Here we favour the second option as the most simple. This only requires: + A ROS2 installation in the host. Follow the [official ROS2 installation guide](https://docs.ros.org/en/humble/Installation.html) for the distro of choice. + Launch the Visual-ROS container sharing host network stack: ```bash node-red-ros2-plugin/docker$ docker build --build-arg ROS_DISTRO=humble -t visualros:humble . $ docker run -ti --name turtledemo --network host --ipc host visualros:humble /node_entrypoint.sh node-red ``` ##### Demo steps 1. Launch `turtlesim` on the host by doing: ```bash $ . /opt/ros/humble/setup.sh $ ros2 run turtlesim turtlesim_node ``` A window should appear with a turtle in the middle. 1. Open a web browser on [http://localhost:1880](http://localhost:1880). 1. Create and wire the following nodes: + A `ROS2 Type` node. In the associated dialog set up the turtlesim pose type: `geometry_msgs/Twist`. + A couple of `ROS2 Inject` nodes: one to move the turtle forward and another to spin it. Wire both nodes to the `ROS2 Type`. Open the associated dialogs and take into account that: - mover forward means `linear.x = 1` - spin means `angular.z = 1` + A `ROS2 Publisher` node. Wire it to the `ROS2 Type` node. Open the associated dialog and set up as: - Topic the `turtle/cmd_vel`. - Use the default ROS2 domain 0. 1. Click the `Deploy` button. ![turtlesim](./docs/turtlesim.gif) Now click on the inject nodes buttons within the editor and see how the turtle moves. This [json file](./docs/turtlesim.json) can be imported to Node-RED in order to reproduce the flow. ### FIWARE nodes usage The [FIWARE Context Broker](https://fiwaretourguide.readthedocs.io/en/latest/core/introduction/) uses a REST API to provide information. This interface do not exactly follows a Publisher/Subscriber model but can be adapted to do so: - Broker entities are mapped as Publisher/Subscriber topics. - Types are described using IDL which works as a subset of the NGSI type system. #### FIWARE configuration node A [Node-RED config node](https://nodered.org/docs/user-guide/concepts#config-node) is provided to set up the FIWARE Context Broker IPv4 address which is a global selection. ![FIWARE Config Node](./docs/FIWAREsettings.jpg) #### FIWARE Publisher

	This node represents a FIWARE publisher able to publish messages on a specific topic.
	The dialog provides controls to configure: Topic Element that acts as a bus for nodes to exhange messages. It matches the Context Broker entity concept. Context Broker Address of the FIWARE Context Broker this node will connect to. A specific config node dialog will be open in order to ease address and port selection.

#### FIWARE Subscriber

	This node represents a FIWARE subscriber. It is able to subscribe on a specific topic and receive all messages published for it.
	The dialog provides controls to configure: Topic Element that acts as a bus for nodes to exchange messages. It matches the Context Broker entity concept. Context Broker Address of the FIWARE Context Broker this node will connect to. A specific config node dialog will be open in order to ease address and port selection.

### FIWARE Examples #### FIWARE Basic Publication Example Let's use a custom type. 1. Launch docker compose as explained [here](./docker/README.md). 1. Create and wire the following nodes: + An `IDL Type` node. Open the associated dialog and introduce the following idl: ```c module custom_msgs { module msg { struct Message { string text; uint64 value; }; }; }; ``` + A `FIWARE Publisher` node. Open the associated dialog and set up the publisher: `Topic` : hope `Context Broker` : `192.168.42.14:1026` Note the address and port of the Context Broker was specified in the `compose.yaml` file. + A `ROS Inject` node. Open the associated dialog and fill in the fields: `text` : Hello World! `value` : 42 1. Deploy the flow pressing the corresponding button. 1. Once deployed, click on the inject node button within the editor. The Context Broker should have created an entity associated to the topic (`hope`) with the values provided in the inject node. In order to check it, the FIWARE Context Broker can be directly queried using its REST API (note that in the `compose.yaml` file the Context Broker port 1026 is mapped to the host machine). Open a console on the host and type: ```bash $ curl -G -X GET "http://localhost:1026/v2/entities" -d "type=custom_msgs::msg::Message" -d "id=hope" ``` It should return the following json: ```json [ { "id": "hope", "type": "custom_msgs::msg::Message", "text": { "type": "Text", "value": "Hello World!", "metadata": {} }, "value": { "type": "Number", "value": 42, "metadata": {} } } ] ``` ![FIWARE Publisher](./docs/FIWAREPublisher.gif) #### FIWARE Basic Subscription Example In this case, a builtin ROS2 type (`geometry_msgs/Point`) will be used. 1. Launch docker compose as explained [here](./docker/README.md). 1. Create and wire the following nodes: + A `ROS2 Type` node. Open the associated dialog and select: `Package` : geometry_msgs `Message` : Point + A `FIWARE Subscriber` node. Open the associated dialog and set up the subscriber: `Topic` : position `Context Broker` : `192.168.42.14:1026` + A `debug` node from the `common` palette section. Open the associated dialog and set it up to show the x coordinate of the point: `Output` : `msg.x` 1. Deploy the flow pressing the corresponding button. 1. Publish a message on that topic from the FIWARE REST API. Because the `compose.yaml` maps the FIWARE Context Broker port to a host one (1026) is possible to reach it from the host machine. Open a console on the host and type: ```bash $ curl http://localhost:1026/v2/entities -H 'Content-Type: application/json' -d @- < This project (DIH² - A Pan‐European Network of Robotics DIHs for Agile Production) has received funding from the European Union’s Horizon 2020 research and innovation programme under grant agreement No 824964