search

ezWheelSAS / swd_ros2_controllers

ROS2 nodes to control motors powered by the ez-Wheel Safety Wheel Drive (SWD®) technology.
https://www.ez-wheel.com/
GNU Lesser General Public License v2.1
6 stars 3 forks source link

readme

ez-Wheel SWD® ROS2 Controllers

Overview

This package has been tested on ROS2 Foxy, Galactic, Humble and Iron. It contains ROS2 nodes to control motors powered by the ez-Wheel Safety Wheel Drive (SWD®) technology.

SWD-Core SWD-125 SWD-150 SWD-StarterKit
SWD® Core SWD® 125 SWD® 150 SWD® StarterKit
Safety gear motor Medium duty Safety Wheel Drive Heavy duty Safety Wheel Drive Development kit for AGV and AMR

Users should regularly inform themselves about updates of this driver (Activating GitHub notifications with "Watch", 'All activity' button on top of this page).

Prerequisites

Pre-built debian package

It is available for the following platforms:

Installation

METHOD 1: Ubuntu package manager

In order to install swd_ros2_controllers with apt, you need to add ez-Wheel repository to your Apt sources configuration file as sudo in: /etc/apt/sources.list. Type the following command:

echo "deb http://packages.ez-wheel.com:8081/ubuntu/ $(lsb_release -cs) main" | sudo tee -a /etc/apt/sources.list

Then, download and add the GPG key. Type the following command:

sudo bash -c "wget -qO - http://packages.ez-wheel.com:8081/archive.key | gpg --dearmor > /etc/apt/trusted.gpg.d/ez-wheel-keyring.gpg"

Now, you should be able to install ez-Wheel's packages using Advanced Packaging Tool (apt):

sudo apt update && sudo apt install swd-services ros-${ROS_DISTRO}-swd-ros2-controllers

METHOD 2: Compiling from source

To compile the package, make sure you added ez-Wheel repository to your Apt sources configuration file as sudo in: /etc/apt/sources.list, as specified above in METHOD 1. So that you can install required swd-services, by typing:

sudo apt-get update && sudo apt install swd-services

In the following instructions, replace <rosdistro> with the name of your ROS2 distro (e.g., galactic).

source /opt/ros/<rosdistro>/setup.bash
mkdir -p ~/ros2_ws/src/
cd ~/ros2_ws/src/
git clone https://github.com/ezWheelSAS/swd_ros2_controllers.git
cd ..
colcon build
source ~/ros2_ws/install/setup.bash

Usage

A- On the SWD® Starter Kit

The package comes with a preconfigured launchfile which can be started using the ros2 launch command:

export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/opt/ezw/usr/lib
ros2 launch swd_ros2_controllers swd_diff_drive_controller.launch.py

You can always use the node with the ros2 run command, the minimum required parameters are:

export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/opt/ezw/usr/lib
ros2 run swd_ros2_controllers swd_diff_drive_controller --ros-args -p baseline_m:=0.485

The corresponding D-Bus services have to be started in order to use the nodes.

Example with the SWD® Starter Kit:

dbus-launch > /tmp/SYSTEMCTL_dbus.id ## [OPTIONAL]
export $(cat /tmp/SYSTEMCTL_dbus.id) ## [OPTIONAL]
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/opt/ezw/usr/lib
/opt/ezw/usr/bin/ezw-smc-service /opt/ezw/usr/etc/ezw-smc-core/swd_left_config.ini
/opt/ezw/usr/bin/ezw-smc-service /opt/ezw/usr/etc/ezw-smc-core/swd_right_config.ini

Example of configuration files for SWD® Starter Kit:

swd_left_config.ini

# SMC Drive service config file
contextId = 12
nodeId = 4
coreNodeId = 6
coreNodeIsMaster = true # Slave:false Master:true
canDevice = can0
dbusNamespace = swd_left

HWConfigurationEntry = SWD_CORE
HWConfigurationFile = /opt/ezw/data/configuration.json

CANOpenEDSFile = /opt/ezw/usr/etc/ezw-canopen-dico/swd_core.eds

swd_right_config.ini

# SMC Drive service config file
contextId = 12
nodeId = 5
coreNodeId = 7
coreNodeIsMaster = true # Slave:false Master:true
canDevice = can0
dbusNamespace = swd_right

HWConfigurationEntry = SWD_CORE
HWConfigurationFile = /opt/ezw/data/configuration.json

CANOpenEDSFile = /opt/ezw/usr/etc/ezw-canopen-dico/swd_core.eds

configuration.json

[
   {
      "name": "SWD_CORE",
      "nbStepRevolutionElec": 6,
      "nbPolePair": 5,
      "reduction": 14.0,
      "diameter": 125.0
   }
]

B- On your own IPC

As the minimal SWD® Starter Kit config files do not exist on your IPC, you can install them manually as specified above or install them via a third package.

In this case, make sure you added ez-Wheel repository to your Apt sources configuration file as sudo in: /etc/apt/sources.list, as specified above in METHOD 1.

First, create swd_sk user with sudo rights, with swd_sk as default password:

sudo addgroup swd_sk
sudo useradd -m -s /bin/bash -g swd_sk swd_sk
sudo bash -c 'echo swd_sk:swd_sk | chpasswd'
sudo usermod -aG sudo swd_sk

Then log in with user swd_sk:

su - swd_sk

Then install swd-system-config-2wheels using:

sudo apt-get update && sudo apt install swd-system-config-2wheels

This package will configure your system to start at boot up four new services (with user swd_sk account):

and add the following config files as specified above :

This packages comes also with the commissioning scripts used for each wheels :

You can modify them and apply the commissioning using:

cd /opt/ezw/commissioning/
./swd_left_4_commissioning.py
./swd_right_5_commissioning.py

Then refer to "Usage on a SWD® Starter Kit" for more information.

About ROS2 swd_diff_drive_controller node

This controller manages two ez-Wheel SWD® wheels as a differential kinetic robot.

Parameters

Subscribed Topics

Published Topics

Custom message types

swd_ros2_controllers::msg::SafetyFunctions message

This message provides information about the state of the Safety functions. The value is True if the safety function is enabled.

std_msgs/Header header
bool safe_torque_off                        # Safe Torque Off (STO)
bool safe_brake_control                     # Safe Brake Control (SBC)
bool safety_limited_speed_1                 # Safety Limited Speed 1 (SLS_1)
bool safety_limited_speed_2                 # Safety Limited Speed 2 (SLS_2)
bool safe_direction_indication_forward      # Safe Direction Indication (positive)
bool safe_direction_indication_backward     # Safe Direction Indication (negative)

The main safe drive function is the STO whereby the immediately torque-off on the motor may be accompanied by an SBC command to close the brakes. The SLS functions cause the drive to decelerate (if required) and monitor whether the velocity is held within the defined limits. The functions SDIp and SDIn enable the motor movement only in the corresponding (positive or negative) direction.

Support

For any questions, open a GitHub issue.

About ez-Wheel®

ez-Wheel® is an innovative company founded in 2009 and located in Angoulême, France. ez-Wheel has developed the first industrial wheel drive, integrating motorisation, embedded electronics and batteries.

This revolutionary solution, which quickly turns any manually handled platform into an electrically assisted one. Our solutions have been adopted by hundreds of end-users to improve productivity and prevent work accidents caused by manual handling. Our products are used in a variety of applications, in fields of Automotive, Factory logistics, Warehouses, Food processing, Hospitals and Pharmaceutical industries.

SWD® products tackles industrial robotics applications, like Autonomous Mobile Robots (AMRs) and Automatic Guided Vehicles (AGVs). It provides a unique solution for safety critical systems, with safety features related to the ISO 3691-4 standard.

ez-Wheel® has developed a unique know-how in embedded electronics, including safety critical systems, applied to battery powered electric traction.

Troubleshooting

Update swd-services

sudo apt update && sudo apt install swd-services

Check if other swd-packages can be upgraded:

sudo apt search swd-

Error during commissioning

Before applying commissioning, stop swd_diff_drive_controller node. Then, execute again python scripts in the commissionning directory:

./swd_"[...]"_commissioning.py

Error with dbus session

export LD_LIBRARY_PATH=/opt/ezw/usr/lib
export $(cat /tmp/SYS*.id)

Then restart ezw-swd-left service and ezw-swd-right service.

Debug SWD with diagnostic tool

Use remote.py script installed with swd-services package in /opt/ezw/usr/sbin directory, with its dbusNamespace as argument, e.g.:

/opt/ezw/usr/sbin/remote.py smc_drive
/opt/ezw/usr/sbin/remote.py swd_left
/opt/ezw/usr/sbin/remote.py swd_right

CAN socket is not configured


sudo ip link set down can0
sudo ip link set can0 up type can bitrate 1000000 restart-ms 100
sudo ip link set can0 txqueuelen 1000