Add some documentation

NiryoRobotics · Dec 22, 2017 · 291cb07 · 291cb07
1 parent 69cae3d
commit 291cb07
Show file tree

Hide file tree

Showing 12 changed files with 300 additions and 38 deletions.
diff --git a/README.md b/README.md
@@ -2,17 +2,22 @@
 
 (Niryo One : [https://niryo.com](https://niryo.com/?utm_source=github))
 
---- DOCUMENTATION IN PROGRESS, WILL BE UPDATE WITH MORE INFO ---
+![niryo one rviz simulation](https://niryo.com/wp-content/uploads/2017/12/ros_rviz_niryo_one.png)
 
 This repository contains all ROS packages used on Niryo One (Raspberry Pi 3 - Xubuntu for ARM).
 
-## How to install Niryo One ROS packages on your computer (x86)
+## How to use Niryo One with a graphical interface ?
+
+You can [download Niryo One Studio](https://niryo.com/download/?utm_source=github) (Linux, Windows and MacOS compatible).
+
+## How to install Niryo One ROS packages on your computer (x86) - Simulation Mode
 
 Requirements :
 * Ubuntu 16.04
 * ROS kinetic  (other versions are not supported)
 
-First install ROS kinetic "Desktop-Full" (tutorial [here](http://wiki.ros.org/kinetic/Installation/Ubuntu))
+First install ROS kinetic "Desktop-Full" (tutorial [here](http://wiki.ros.org/kinetic/Installation/Ubuntu)).
+
 You'll need to install some additional ROS packages :
 ```
 sudo apt-get install ros-kinetic-robot-state-publisher ros-kinetic-moveit ros-kinetic-manipulation-msgs ros-kinetic-rosbridge-suite ros-kinetic-joy ros-kinetic-ros-control ros-kinetic-ros-controllers
@@ -37,27 +42,17 @@ You can now launch Rviz with Niryo One :
 ```
 roslaunch niryo_one_description display.launch
 ```
--  If you find a problem please send us a message (support@niryo.com) so we can quickly correct any mistake
-
 
 Niryo One ROS packages have been developed with **ROS kinetic, on Ubuntu 16.04**. Other ROS versions and OS distributions are not supported.
 
+## Niryo One ROS Stack documentation
 
-## How to use Niryo One with a graphical interface ?
-
-You can download Niryo desktop software (Linux, Windows and MacOS compatible) : _coming soon..._
-
-## Niryo One full documentation
+Here's a global overview of the Niryo One ROS Stack :
 
-_coming soon..._
+![niryo one ros stack - global overview](https://niryo.com/wp-content/uploads/2017/12/niryo_one_ros.png)
 
-COMING SOON :
-- Instructions to run ROS packages on Niryo One Raspberry Pi 3 official image (Xubuntu)
-- Code diagrams for a better understanding of all the packages and dependencies
-- Detailed description of all packages
-- Code examples to use the Niryo One Python API
+**You can find more specific and detailed info in each package's README.**
 
+If you have a question and you don't find the answer here or on our [FAQ](https://niryo.com/niryo-one-faq/?utm_source=github) page, please send us an email at support@niryo.com.
 
-Packages forked from other repositories :
-- dynamixel_sdk : added compatibility with custom Niryo Raspberry Pi 3 shield
-- mcp_can (from MCP_CAN, an Arduino library) : made compatible with Raspberry Pi 3
+Thank you !
diff --git a/dynamixel_sdk/README.md b/dynamixel_sdk/README.md
@@ -0,0 +1,5 @@
+# Dynamixel SDK
+
+This package has been forked from the official [dynamixel_sdk](https://github.com/ROBOTIS-GIT/DynamixelSDK) package. 
+
+It has been adapted to work on the Niryo custom Raspberry Pi 3 shield, using the [wiringPi](http://wiringpi.com/) library.
diff --git a/mcp_can_rpi/README.md b/mcp_can_rpi/README.md
@@ -1,15 +1,14 @@
-RPI3 library for MCP2515 module (CAN bus interface) through SPI GPIOs
+# mcp\_can\_rpi
 
-Forked from : https://github.com/coryjfowler/MCP_CAN_lib
+Raspberry Pi 3 library for MCP2515 module (CAN bus interface) through SPI GPIOs
 
-The library has the same features, but is working on a Raspberry Pi 3.
+Forked from [MCP_CAN](https://github.com/coryjfowler/MCP_CAN_lib) library.
 
-One of the main difference is we don't handle SPI Chip Select PIN. This is already done by the wiringPi library, and
-all PINS for SPI are already predefined (spi channel 0 or 1).
-
-This library is licensed under GPLv3, for now.
+The MCP2515 module is a SPI-CAN interface. The MCP_CAN library is using the SPI protocol on Arduino to program and use this module. It has been adapted here to work with the Raspberry Pi 3 GPIOs, using the SPI functions of the  [wiringPi](http://wiringpi.com/) library.
 
--------------------------------------------------------
+---
 
---> More documentation will be published soon. <-- 
+One of the main difference is we don't handle SPI Chip Select PIN. This is already done by the wiringPi library, and
+all PINs for SPI are already predefined (spi channel 0 or 1).
 
+To poll the MCP2515 module (to see if there is any data to read), the _digitalRead_ function of wiringPi is used.
diff --git a/niryo_one_bringup/README.md b/niryo_one_bringup/README.md
@@ -0,0 +1,35 @@
+# Niryo One Bringup
+
+This packages provides config and launch files to start Niryo One and ROS packages with various parameters.
+
+Launch files (in _launch_ folder) :
+
+### niryo\_one\_base
+
+Setup many rosparams, this package should be launched before any other package.
+
+### controllers
+
+Starts Niryo One _driver_, _tools\_controller_, _ros\_control_ and _robot\_state\_publisher_ packages.
+
+### robot\_commander
+
+Starts robot command utilities to move the arm and tools.
+
+### user\_interface
+
+Starts joystick interface (Xbox controller) and Blockly server (Blockly is a graphical programming library, integrated in Niryo One Studio).
+
+### rpi\_setup
+
+The main package to launch on a Raspberry Pi 3. Also launches _rosbridge_, _niryo\_one\_base_,  _controllers_, _robot\_commander_, and _user\_interface_. This package is automatically launched when Niryo One boots (Niryo One RPi3 image).
+
+### desktop\_rviz\_simulation
+
+This is the main package for simulation mode. It launches _niryo\_one\_base_, _controllers_, _robot\_commander_, _user\_interface_, _rosbridge_, and Rviz to see a 3D view of Niryo One. The _controllers_ package is launched with a simulation flag, so the hardware-related stuff is not used.
+
+Note that you need to launch this file on your computer, with 3D packages installed. This will not work on the Niryo One RPI3 image.
+
+---
+
+You can find more info about what the packages do in each package's README.
diff --git a/niryo_one_commander/README.md b/niryo_one_commander/README.md
@@ -0,0 +1,15 @@
+# Niryo One Commander
+
+This package is a high-level interface built on top of Niryo One controllers and Moveit! utilities.
+
+The robot\_action\_server provides an actionlib server. All robot commands go trough this server (from Niryo One Studio, Blockly server, Python API, etc). 
+
+Here's what it does :
+* Handles concurrent requests 
+* Checks if the command can't be processed due to other factors (ex: learning mode)
+* Validates parameters
+* Calls required controllers and returns appropriate status and message
+
+The Action for this server is RobotMove.action (including RobotMoveCommand.msg for the goal), and can be found in [niryo\_one\_msgs](https://github.com/NiryoRobotics/niryo_one_ros/tree/master/niryo_one_msgs) package.
+
+The files _robot\_commander_, _arm\_moveit\_commander_, and _tool\_commander_ are used by this server to call the required controllers (tools, rpi, Moveit! + ros_control)
diff --git a/niryo_one_description/README.md b/niryo_one_description/README.md
@@ -2,12 +2,12 @@
 
 This package contains URDF file and meshes (collada + stl) for Niryo One.
 
-**Notice** : 3D visualization is not available on the Niryo One Raspberry Pi image. To use the following commands, you must have installed ROS on your computer and downloaded the Niryo One ROS packages. 
+**Note** : 3D visualization is not available on the Niryo One Raspberry Pi image. To use the following commands, you must have installed ROS on your computer and downloaded the Niryo One ROS packages. 
 
 * To display Niryo One on Rviz :
 
 ```
 roslaunch niryo_one_description display.launch
 ```
 
-Also, as you can see, there is a file named "without_mesh_niryo_one.urdf". This file is used on the Raspberry Pi 3 to avoid a segmentation fault when using visuals, due to some ARM dependencies of Moveit!.
+Also, as you can see there is a file named "without\_mesh\_niryo\_one.urdf". This file is used on the Raspberry Pi 3 to avoid a segmentation fault when using visuals, due to some ARM dependencies of Moveit!.
diff --git a/niryo_one_driver/README.md b/niryo_one_driver/README.md
@@ -0,0 +1,15 @@
+# Niryo One Driver
+
+This packages provides an interface to _ros\_control_ and handles the hardware control of motors.
+
+Here's a global overview of this package :
+
+![niryo one driver - global overview](https://niryo.com/wp-content/uploads/2017/12/niryo_one_driver_global_overview.png)
+
+For each kind of motor, this packages contains a driver + a communication class between the driver and _ros\_control_.
+
+2 types of motors :
+* Dynamixel XL_320 motors for axis 5, 6 and some tools (grippers, vacuum pump). 
+* Niryo Stepper Motors, connected to a CAN bus (you can find the firmware for the motors [here](https://github.com/NiryoRobotics/niryo_stepper))
+
+The _ros\_interface_ class is an interface between Niryo One hardware and the ROS ecosystem. It handles specific commands (learning mode, calibration, ...) and sends some data (hardware status, connected tool, ...).
diff --git a/niryo_one_modbus/README.md b/niryo_one_modbus/README.md
@@ -1,7 +1,9 @@
 # Niryo One Modbus/TCP Server
 
 The Modbus/TCP server is running on port 5020 by default.
+
 It has been built on top of the [pymodbus](http://pymodbus.readthedocs.io/en/latest/index.html) library.
+
 This enables you to make Niryo One communicate with a PLC, or another computer in the same network.
 
 All 4 Modbus datastores are implemented : _Coil_, _Discrete Input_, _Holding Register_, _Input Register_. Each datastore has a different set of functionalities. Note that **each datastore contains a completely different set of data**.
@@ -14,10 +16,12 @@ Address tables start at 0.
 ## Coil
 
 Each address contains a 1bit value.
+
 READ/WRITE (the stored values correspond to the last given command, not the current robot state)
+
 Accepted Modbus functions :
-  * 0x01: READ_COILS
-  * 0x05: WRITE_SINGLE_COIL
+  * 0x01: READ\_COILS
+  * 0x05: WRITE\_SINGLE\_COIL
 
 This datastore can be used to set Digital I/O mode and state. Digital I/O numbers used for Modbus:
 * 0 : 1A
@@ -36,9 +40,11 @@ This datastore can be used to set Digital I/O mode and state. Digital I/O number
 ## Discrete Input
 
 Each address contains a 1bit value.
+
 READ-ONLY
+
 Accepted Modbus functions :
-* 0x02: READ_DISCRETE_INPUTS
+* 0x02: READ\_DISCRETE\_INPUTS
 
 This datastore can be used to read Digital I/O mode and state. See _Coil_ section above for digital I/O number mapping.
 
@@ -50,10 +56,12 @@ This datastore can be used to read Digital I/O mode and state. See _Coil_ sectio
 ## Holding Register
 
 Each address contains a 16bit value.
+
 READ/WRITE (the stored values correspond to the last given command, not the current robot state)
+
 Accepted Modbus functions :
-* 0x03: READ_HOLDING_REGISTERS
-* 0x06: WRITE_SINGLE_REGISTER
+* 0x03: READ\_HOLDING\_REGISTERS
+* 0x06: WRITE\_SINGLE\_REGISTER
 
 |Address| Description |
 |-------|-------------|
@@ -65,9 +73,11 @@ Accepted Modbus functions :
 ## Input Register
 
 Each address contains a 16bit value.
+
 READ-ONLY
+
 Accepted Modbus functions :
-* 0x04: READ_INPUT_REGISTERS
+* 0x04: READ\_INPUT\_REGISTERS
 
 |Address| Description |
 |-------|-------------|

diff --git a/niryo_one_python_api/README.md b/niryo_one_python_api/README.md
@@ -4,7 +4,7 @@ To use Python API :
 
 1. Connect to Niryo One via ssh
 
-2. Create a Python file 
+2. Create a Python file
 
 ```
 touch test_python_api.py
@@ -26,6 +26,133 @@ n = NiryoOne()
 try:
     # Your code here
 except NiryoOneException as e:
-    print e 
+    print e
     # Handle errors here
 ```
+
+### Documentation - Class methods
+
+##### activate\_learning\_mode
+
+Params: 
+* activate (0 or 1)
+
+Activate or deactivate learning mode (= disable/enable torque on motors).
+
+##### move\_joints
+
+Params:
+* joints (array of 6 joints)
+
+Move the arm with a joint command.
+
+##### move\_pose
+
+Params:
+* position x (m)
+* position y (m)
+* position z (m)
+* rotation x (rad)
+* rotation y (rad)
+* rotation z (rad)
+
+Move the arm with a pose command.
+
+##### shift\_pose
+
+Params:
+* axis (0: pos.x, 1: pos.y, 2: pos.z, 3: rot.x, 4: rot.y, 5: rot.z)
+* value (m)
+
+Move the arm by shifting the current pose on <axis> by <value>.
+
+##### pin\_mode
+
+Params:
+* pin (GPIO number)
+* mode (0: OUTPUT, 1: INPUT)
+
+Set a digital I/O pin on INPUT or OUTPUT mode.
+
+##### digital\_write
+
+Params:
+* pin (GPIO number)
+* state (0: LOW, 1: HIGH)
+
+Set a digital I/O pin to LOW or HIGH. Note that the pin must have been previously set as OUTPUT.
+
+##### digital\_read
+
+Params:
+* pin (GPIO number)
+
+Returns the current pin state (0: LOW, 1: HIGH).
+
+##### change\_tool
+
+Params:
+* tool id (0 to detach current tool)
+
+Change current attached tool. **Before you execute any action on a tool, you have to select it with this method.**
+
+##### open\_gripper
+
+Params:
+* tool id
+* open speed (between 0 and 1000, recommended : between 100 and 500)
+
+Open gripper at selected speed.
+
+##### close\_gripper
+
+Params:
+* tool id
+* close speed (between 0 and 1000, recommended : between 100 and 500)
+
+Close gripper at selected speed. The gripper will stop when it detects the object to grab.
+
+##### pull\_air\_vacuum\_pump
+
+Params:
+* tool id
+
+Activate vacuum pump (pick object).
+
+##### push\_air\_vacuum\_pump
+
+Params: 
+* tool id
+
+Deactivate vacuum pump (place object)
+
+##### setup\_electromagnet
+
+Params:
+* tool id
+* pin (GPIO number)
+
+Setup electromagnet on digital I/O <pin> (set the pin mode to OUTPUT). You need to select and setup the electromagnet before using it.
+
+##### activate\_electromagnet
+
+Params:
+* tool id
+* pin (GPIO number)
+
+Activate electromagnet on digital I/O <pin> (pick object). This will set the pin state to HIGH.
+
+##### deactivate\_electromagnet
+
+Params:
+* tool id
+* pin (GPIO number)
+
+Deactivate electromagnet on digital I/O <pin> (place object). This will set the pin state to LOW.
+
+##### wait
+
+Params:
+* time (seconds)
+
+Blocks and wait for <time> seconds.
diff --git a/niryo_one_rpi/README.md b/niryo_one_rpi/README.md
@@ -0,0 +1,11 @@
+# Niyo One Raspberry Pi 3
+
+This packages handles all the external hardware (everything else than the motors) of Niryo One, and provides many utilities for the Raspberry Pi 3 :
+* Digital I/O panel : gets commands and sends the current state of digital I/Os. Also controls tools like the electromagnet.
+* LED : sets the LED color.
+* Top Button : executes actions when the button is pressed.
+* Wifi : handles the Raspberry Pi 3 Wi-FI connection (connected to a local network, or in hotspot mode).
+* ROS log : can remove all previous logs on startup to prevent a lack of disk space in the long run (SD cards do not have infinite storage).
+* ROS setup : can launch different processes and roslaunch files from code, with the possibility to add a delay before launching. Practicle on Raspberry Pi, where the computation power is quite low compared to a standard laptop.
+
+Note that this package should not be used when you are using Niryo One ROS stack on your computer, in simulation mode.