Niryo One User manual

Niryo One
User Manual
21/02/2019

2
Summary
1. Introduction....................................................................................................................... 4
1.1 Purpose...................................................................................................................................................... 4
1.2 Safety precautions ................................................................................................................................. 4
1.3 Software versions ................................................................................................................................... 4
1.4 How to update Niryo One software................................................................................................ 4
2. Niryo One - Physical external interfaces......................................................................... 6
2.1 Overview.................................................................................................................................................... 6
2.2 Panel connector...................................................................................................................................... 7
3. Get started with Niryo One .............................................................................................. 9
3.1 Niryo One Studio.................................................................................................................................... 9
3.1.1 Overview........................................................................................................................................... 9
3.1.2 How to launch Niryo One Studio?.......................................................................................... 9
3.1.3 Left menu ......................................................................................................................................... 9
3.2 Power ON and power OFF the robot............................................................................................10
3.2.1 Power ON the robot...................................................................................................................10
3.2.2 Power OFF the robot..................................................................................................................11
3.3 Meaning of the LED color .................................................................................................................12
3.4 Top button..............................................................................................................................................13
3.5 Wi-Fi connection ..................................................................................................................................14
3.5.1 Connect to the robot in “hotspot mode” (LED is blue).................................................15
3.5.2 Connect to the robot using an Ethernet cable ................................................................15
3.5.3 Connect the robot to a Wi-Fi network................................................................................17
3.5.4 Connect to the robot in “connected mode” (green LED) ............................................18
3.5.5 Make the robot go back to “hotspot mode”....................................................................19
3.5.6 Use another IP address (custom) ..........................................................................................19
3.5.7 Give a custom name to the robot.........................................................................................20
3.6 Robot Calibration.................................................................................................................................20
3.6.1 Auto-calibration...........................................................................................................................21
3.6.2 Manual calibration (recommended) ....................................................................................21
3.6.3 Require a new calibration ........................................................................................................23
4. Command the robot........................................................................................................24
4.1 State section and learning mode ...................................................................................................24

3
4.2 Move the robot.....................................................................................................................................25
4.3 Use the tools..........................................................................................................................................27
4.3.1 Overview.........................................................................................................................................27
4.3.2 How to plug the tools? .............................................................................................................28
4.3.3 Select a tool...................................................................................................................................30
4.3.4 Control a tool................................................................................................................................31
4.4 Digital I/O panel ...................................................................................................................................31
4.5 Saved positions.....................................................................................................................................33
4.5.1 Overview.........................................................................................................................................33
4.5.2 Save a position.............................................................................................................................34
4.5.3 How to use a saved position? ................................................................................................34
4.6 Niryo Blocks............................................................................................................................................35
4.7 Sequences...............................................................................................................................................39
4.7.1 Save a sequence..........................................................................................................................39
4.7.2 Save a sequence from Niryo Blocks.....................................................................................41
4.8 Use the top button to trigger a (set of) sequences.................................................................42
4.9 Use a joystick controller to move the robot ..............................................................................44
4.9.1 Connect and enable the joystick controller ......................................................................44
4.9.2 Use the joystick controller .......................................................................................................45
5. Settings.............................................................................................................................46
5.1 Raspberry Pi 3B settings....................................................................................................................46
5.1.1 ROS logs (advanced users)......................................................................................................46
5.1.2 Shutdown the robot...................................................................................................................47
5.2 Software versions .................................................................................................................................47
5.3 Hardware Status ...................................................................................................................................48
5.3.1 Overview.........................................................................................................................................48
5.3.2 Motor connection problem.....................................................................................................49
5.3.3 What to do if you have a hardware problem?.................................................................49
5.4 Debug and logs ....................................................................................................................................50
5.4.1 Overview.........................................................................................................................................50
5.4.2 Debug motors one by one ......................................................................................................51
6. Going further ...................................................................................................................52

4
1. Introduction
1.1 Purpose
This manual describes the functions available for Niryo One, and shows you how to control the
robot from Niryo One Studio.
You can find more documentation on our website.
1.2 Safety precautions
⚠In order to avoid possible damages or injuries:
Do not use Niryo One outside
Do not put the robot on a not stable surface
Do not put the robot on a non-flat and non-horizontal surface
Do not put the robot in a humid environment, or near water
Do not let children use the robot alone
Do not disassemble the robot if it is still powered on
Respect all the electrical rules and warnings that you can find on this manual
1.3 Software versions
There are 3 software layers when you use Niryo One. From higher to lower:
Niryo One Studio (desktop app)
Niryo One Raspberry Pi image (robot software)
Niryo Stepper (motors firmware)
When you receive a Niryo One, the versions of the 3 layers are all compatible between them.
⚠If you update one of those software layer, you may have to update the other layers (in this
case you’ll get a warning on Niryo One Studio when you connect to the robot).
⚠This manual is valid for the following versions:
Niryo One Studio : 2.X.X
Niryo One Raspberry Pi image : 2.X.X
Niryo Stepper : 2.X.X
1.4 How to update Niryo One software
You can use those 3 tutorials:

5
Update Niryo One Studio
Update Raspberry Pi 3B image
Update Niryo Steppers
On the download page, you can also find all kinds of resources to download.

6
2. Niryo One - Physical external interfaces
2.1 Overview
There are many physical interfaces at the back of Niryo One. Here is an overview and some
warnings about things you should be careful about.
The functionalities related to each interface will be covered throughout this manual.
1. Top button
2. Ethernet port of the Raspberry Pi 3B
3. USB port * 4.
4. LED.
5. CAN bus connection for Niryo Steppers * 2. Not used yet.
6. Dynamixel XL-320 connector. Used for the vacuum pump
7. Dynamixel XL-430 connector. Not used yet
8. 12 V switch output * 2. Actionable through software

7
9. GPIO panel * 2. Total 6 digital pins, actionable through software. You can use GPIO1 and
GPIO2 pins as 5V digital pins (mode: input or output, state: high or low).
10. Power switch
11. Power adapter connector
⚠Ensure your power adapter has a 12V output and is able to provide 6A. Lower output
voltage and current may cause the robot to fail to move correctly. Higher output voltage and
current may permanently damage the robot, and can be a cause of fire.
2.2 Panel connector
Here is a more detailed view of the panel connector:
⚠Electrical rules and warnings for the panel connector:

8
The XL-320 (Dxl-Data1) interface should only be used to connect XL-320 motors.
The XL-430 (Dxl-Data2) interface should only be used to connect XL-430 motors.
Do not make a short circuit between the GND and 12V pins of the switches (SW1 and
SW2) and do not connect the switches together.
The SW* interfaces can provide 500 mA maximum.
The device you connect to GPIOs pins must operate at 5V, not more, not less. Add a
voltage divider if needed.
Do not make a short circuit between GND, 5V, and any other GPIO pin.
Not respecting these rules may lead to various damages on the electronics boards or motors.

9
3. Get started with Niryo One
3.1 Niryo One Studio
3.1.1 Overview
Niryo One Studio is the desktop application (Windows - MacOS - Linux) for controlling Niryo
One. You can use it to setup the robot, change some settings, move the robot, program a
sequence, etc. In this manual we’ll cover all the available functionalities.
3.1.2 How to launch Niryo One Studio?
Once you’ve downloaded the .zip file from niryo.com, you need to extract the archive. Then go
into the new created folder and search for an executable named “NiryoOneStudio”. Double
click on the executable to start the application. You don’t need to install anything on your
computer.
3.1.3 Left menu

10
The left menu allows you to switch between all the different panels. From top
to bottom:
Robot command (arm, tool, digital I/Os)
Niryo blocks
Saved positions
Saved sequences (+ sequence autorun)
Settings (Wi-Fi, Raspberry Pi, software versions)
Calibration
Hardware status
Debug and logs
All the panels will be explained throughout this manual.
3.2 Power ON and power OFF the robot
3.2.1 Power ON the robot
⚠Before powering on the robot, first make sure that:
The robot is on a flat and stable surface
The power switch is turned off (position 0)
The robot has enough space to move without hitting something or someone
To power on the robot, simply plug the power adapter and switch on the switch button. The
LED on the back of the robot will become red.
⚠Do not unplug or power off the robot now, you may damage the Raspberry Pi 3B inside
the robot, or the micro SD card inside the Raspberry Pi 3B.

11
Wait until the LED turns blue or green. This should take about 2 minutes maximum (maybe
longer for the very first boot). If this is the first time you use the robot, the led will be blue.
Once the LED is blue or green, it means that the robot is fully started and you can start
using it.
3.2.2 Power OFF the robot
⚠Do not power off the robot directly with the power switch or by removing the power
adapter. This is the same as if you directly unplug your own computer without shutting it down
before.
There are 2 possibilities to power off the robot:
1. Press the top button and wait that the LED turns purple (after about 3 seconds). Once the
LED is purple, you can release the button. Now, wait until the LED becomes red. Once the LED
turns red, it means that you can safely switch off the robot and unplug the power adapter.
2. On Niryo One Studio -> “settings” panel, “Raspberry Pi settings” section: Click on the
“Shutdown Niryo One” button and confirm.

12
If the command is successful, the LED will turn purple. Again, wait until the LED becomes red
to switch off the robot and unplug the power adapter.
⚠Powering off the robot before the LED turns red might damage the robot.
3.3 Meaning of the LED color
The LED on the back of the robot can switch to different colors. Here’s the meaning of all the
colors:
Red
When you power on the robot, the LED will first be red. In this situation you have to wait until
the LED changes to blue or green. Do not power off the robot now.
The LED will also become red after you shut down the robot (from top button or from Niryo
One Studio), in this case it means that you can power off the robot and pull the power adapter.
Blue
The LED will be blue when the robot is fully started and in “hotspot mode”. If the robot doesn’t
find any previously saved Wi-Fi network on boot, it will create its own Wi-Fi network, and its IP
address will be 10.10.10.10 (static IP).
Green
The LED will be green when the robot is fully started and connected to a Wi-Fi network.
Purple
The LED will be purple when you have given the robot a shutdown command. This gives you
the information that the robot has received your command (by pressing the top button or via

13
Niryo One Studio), and is currently shutting down. Once the Raspberry Pi 3B is completely shut
down, the LED will turn red, meaning that you can power off the robot and unplug the power
adapter.
Blue or green + blinking red
If the LED is blue or green (meaning: robot is fully started), but blinking red every second, it
means that there is a motor connection problem. You can get more info about this motor
connection problem on Niryo One Studio.
3.4 Top button
The top button has multiple functionalities.
All the functionalities will be usable only after the robot has been fully started (LED green
or blue)
The different functionalities will be triggered depending on how long you press the button.
1. If you just press and release the button immediately, the “sequence autorun” functionality
will be triggered. This will start the previously saved sequence for the button. To stop the
execution of the command, simply press and release the button again.
2. If you press the button for more than 3 seconds, the LED will switch to purple. If you release
the button, the robot will start shutting down.
3. If you keep pressing the button for more than 7 seconds, the LED will switch from purple to
blue. If you release the button after that, the robot will not shutdown, but instead switch to
“hotspot mode”. This can be useful when you don’t know on which Wi-Fi network the robot is
connected to (green LED).

14
3.5 Wi-Fi connection
On the right of the toolbar, you can see the current connection state: “Connected to” + IP
address, or “Not connected”.
Once the robot is powered on, and fully started (LED blue or green), you can connect Niryo
One Studio to it.
To do that, click on the arrow icon on the extreme right of the toolbar.
You will see the connection panel:
You can see the current selected IP address on the deep blue chip.
By default the IP is 10.10.10.10, which corresponds to the robot IP address in “hotspot mode”.
We’ll see later how you can change that.

15
3.5.1 Connect to the robot in “hotspot mode” (LED is blue)
In “hotspot mode”, the robot will create its own Wi-Fi network. You can find it on your computer
Wi-Fi manager. The name of the Wi-Fi network starts with “Niryo_One” followed by a series of
numbers and letters, which makes a unique identifier linked to the Raspberry Pi 3B serial
number.
If you gave a custom name to the robot, the name of the Wi-Fi network will be this custom
name, and not the default “Niryo_One + numbers”. This can help you manage multiple robots
more easily.
First, connect your computer to this Wi-Fi network (password: “niryoone”). Note that this
network doesn’t provide an Internet access.
Once connected, you can press the “Connect to Niryo One” button.
You should see a success message on the screen, and the toolbar should look like this:
To disconnect from the robot, open the connection panel again and click on “disconnect”.
3.5.2 Connect to the robot using an Ethernet cable

16
You can also use an Ethernet cable to physically connect your robot with your computer. This
can be useful for example when you are in a Wi-Fi saturated location (exhibition, event, etc.).
To be able to connect to the robot, you’ll need to modify the selected IP address on the
connection panel. Open the connection panel and click on the arrow near the select box to
expand.
Write “169.254.200.200” (static IP) and click on “Choose” to select the IP address. Note that
selecting the IP address just means that this IP will be used by Niryo One Studio, it does not
mean that you are connected to the robot.
Once the IP address on the blue chip is correct, you can connect to the robot.

17
3.5.3 Connect the robot to a Wi-Fi network
One of the main drawback of the “hotspot mode” is that you can’t be connected to the robot
and have Internet access at the same time. Also, if you have multiple robots, it means that you
need to connect your computer to a different Wi-Fi network every time you want to switch
between robots.
To solve that, you can connect the robot to an already existing Wi-Fi network (for example,
your home/school/office Wi-Fi).
Connecting the robot to a Wi-Fi network is usually the best way to connect to Niryo One
The first step is to connect to the robot in “hotspot mode” (or in “connected mode” if the robot
is already connected to a Wi-Fi network and you want to change the Wi-Fi network). Don’t
forget this step: if you are not connected to the robot, you won’t be able to change its Wi-Fi
network.
Once connected to the robot, open the settings panel in Niryo One Studio. On the “Robot Wi-
Fi settings” block, make sure that the displayed IP address is the IP address of the robot you
are currently connected to.
You can now fill in the Wi-Fi name (ssid) and password for the Wi-Fi network you want to
connect the robot to. Make sure to avoid typos in the name and password. Then, click on
“Connect robot to Wi-Fi”.
Niryo One Studio will automatically disconnect from Niryo One. The robot will try to connect
to the Wi-Fi network with the given ssid and password. This can take about 20-30 seconds.

18
If the robot is successfully connected to the Wi-Fi network, the LED will turn green (connected
mode).
If the LED stays blue after 30 seconds, it means that the robot failed to connect to the Wi-Fi
network (for example: bad ssid/password). The robot is still in “hotspot mode” and you can
connect to it again by connecting your computer to the Wi-Fi network created by the robot.
3.5.4 Connect to the robot in “connected mode” (green LED)
The “connected mode” means that the robot is connected to a Wi-Fi network. In this case, you
don’t know what the IP address of the robot inside the network is.
First, connect your computer to the same Wi-Fi network as the robot.
⚠If your computer and your robot are not connected to the same Wi-Fi network, you won’t
be able to connect your computer to the robot.
Then, open the connection panel and click on the “Wi-Fi + Search” button.
This will search for connected robots inside the current Wi-Fi network. All the IP addresses of
robots (you can have multiple robots connected to the same network) that are found will be
displayed on the IP address select box.
If you gave a custom name to the robot, you will see its name instead of the IP address.

19
You can now click on the new displayed IP address (or name) to select it. Make sure that the IP
address is correctly shown in the deep blue chip. (The IP address you see here is the one used
for the entire application)
Now, click on “Connect to Niryo One” to connect Niryo One Studio to the robot.
3.5.5 Make the robot go back to “hotspot mode”
If, at any time, you want the robot to go back to “hotspot mode”, you can:
1. Press the top button for 7 consecutive seconds. Once the LED becomes blue, release the
button and the robot will switch to “hotspot mode”.
2. Or you can click on the “Switch robot to hotspot mode” button inside Niryo One Studio ->
“Settings”→ “Robot Wi-Fi Settings”.
The robot will create its own Wi-Fi network and its IP address inside this network will be
10.10.10.10.
Using the top button can be useful if you “lost” the robot (you don’t know on which Wi-
Fi network the robot is connected to, or your computer doesn’t have access to the Wi-Fi
network to which the robot is connected)
3.5.6 Use another IP address (custom)
In the connection panel, you can click on the arrow to display more options. There is an input
box that you can use to choose any IP address and port you want.

20
When to use this feature?
The two most common cases are when you are:
Using an Ethernet cable between your computer and the robot (the IP will be
169.254.200.200 and port is 9090 by default).
Developing on the robot directly, or on your computer with the simulation mode (for
advanced users). You could for example set the IP to “localhost”. In case you have
modified the web-socket server port of the robot, you’ll have to change it here so the
connection can be successful.
When using a custom IP address, don’t forget to click on the “Choose” button to select
this IP.
3.5.7 Give a custom name to the robot
You can give a custom name to your robot. This name will be used:
When the robot is in hotspot mode. If a custom name for the robot exists, this name
will be used to create the Wi-Fi network name.
When the robot is in connected mode. In Niryo One Studio you will see the robot
represented both by its IP address and its custom name (if any).
To change the name of your robot, go in the “Robot Wi-Fi Settings” panel of the “Settings”
tab.
Fill in the input text box and click on “Set robot name”.
You will have to reboot the robot so the new name can be applied.
3.6 Robot Calibration
After the robot has been successfully launched (LED green or blue), and before you can give a
move command to the robot, you will need to calibrate it. Also, if a Niryo Stepper motor was
disconnected and reconnected, a calibration will be required.
Make sure that you are connected to the robot (“hotspot mode”, “connected mode”, or with
an Ethernet cable).