<commit_before>%% Copyright (C) 2009-2010, <NAME>.
%%
%% This software is provided "as is" without warranty of any kind,
%% either expressed or implied, including but not limited to the
%% implied warranties of fitness for a particular purpose.
%%
%% See the LICENSE file for more information.

\newcommand{\naoqi}{NaoQi\xspace}

\chapter{Nao}
\label{sec:nao}

\section{Introduction}

The \dfn{Nao} is a 60 centimeters tall humanoid robot built by
\dfn{Aldebaran} Robotics.  It has an onboard Geode processor running
Linux, 25 degrees of freedom, two onboard cameras, speakers,
microphones, accelerometers, ultrasound and IR sensors...

\section{Starting up}

Nao comes with an installed version of \urbi.

On some versions of Nao, \urbi is not automatically started upon start-up.
If this is the case, you must take the following steps to activate \urbi:

\begin{itemize}
\item Log in to your Nao using ssh: \lstinline|ssh nao@myNao|
\item Add a line containing \lstinline|urbistarter| to
  \file{/opt/naoqi/preferences/autoload.ini}.
\item Restart your Nao.
\end{itemize}

Those lines might already be present but commented out.

You should be able to connect to your Nao on the port 54000 and send it \us:

\begin{urbiunchecked}
tts.say("Hello, I am Nao."),
// Activate right arm.
armR.load = 1;
// Wave the arm: put it in position
shoulderRollR.val = -0.3 time: 0.5s |
shoulderPitchR.val = -1 speed: 0.9 |
// Wave it
timeout(6s) shoulderRollR.val = -0.4 sin:2s ampli:0.4;
// And put it back down, using the uncompressed name this time
robot.body.arm[right].shoulder.pitch.val = 2 speed:0.9;
// Activate all motors.
motors.on;
// Stand
motion.walkTo(0.1,0,0);
// Start walking...
tag: robot.walk(1),
// ... and interrupt the movement
sleep(2s) | tag.stop;
// Get the list of all devices and the interfaces they implement:
robot.dump;
\end{urbiunchecked}

\section{Accessing joints}
All the Nao joints are accessible through their standard Nao and \urbi names,
and respect the \urbi standard specifications for servo motors: Basically each
motor has a \var{load} field that is linked to the motor stiffness, and a
\var{val} field that can be used to read or write the motor position.

Some motor groups are also provided: they can be used exactly as joints,
but any action performed on a group is sent to all the joints that are a
member of this group.

\begin{urbiunchecked}
// Activate all motors
motors.load = 1;
// Or only all the head motors
head.load = 1;
// Move headYaw to 0.8 in one seconds. Since this commands takes
// one second to execute, terminate with a comma to be able
// to send other commands while it executes.
headYaw.val = 0.8 time: 1s,
// Move headPitch to -0.5 as fast as possible.
headPitch.val = -0.5;
// Move headYaw continuously in a sinusoidal trajectory...
tag: headYaw.val = 0 sin:2s ampli:0.5,
// ...and stop the movement
tag.stop;
\end{urbiunchecked}

The two hands are purposefully not included in the 'motors' group.
Although you can control them using the \var{val} slot, it is recommended that
you use the \var{open()} and \var{close()} methods, since they stop the motors
once the movement is finished.

\subsection{Advanced parameters}

\subsubsection{Trajectory generator period}

The trajectory generators will issue write command at a period given by the
\var{Object.getPeriod} variable. The default is 10ms which is the native period
of \naoqi.

\subsubsection{Motor back-end method}

\urbi can use two different methods to send the joint commands:
\lstinline|DCM::send()|, or \lstinline|ALMotor::setAngle()|.
The mode can be changed by calling \lstinline|motor.setDCMWrite(bool)|.

In \lstinline|setAngle()| mode, each write operation to a joint will
synchronously call the \command{setAngle()} \naoqi method.

In DCM mode, \urbi will set a hook on the DCM update, and send all
commands in this hook using the \command{send()} method.  \urbi will
send commands S milliseconds in the future. S defaults to 50ms, and
can be changed by calling \lstinline|ALMotor.setDCMShift(shiftValue)|.

\subsubsection{Motor command debugging}

The motors implements a debugging mode that can be activated by
calling \lstinline|ALMotor::setTrace(1)|. While activated, it will
write all sent commands to the file \file{/tmp/traj.log}. Each line will
contain the motor number, the command timestamp, and the command
position.  Be careful not to let this feature active while not using
it, as it would quickly fill-up the memory.

\section{Leds}

All Nao's leds and led groups, as defined by \naoqi, are available as
objects in \us. You can set the led values by writing to the slots
\var{val} (intensity between 0 and 1), \var{r}, \var{g}, \var{b}
(color intensity between 0 and 1) or \var{rgb} (RGB value, one byte
each, i.e. 0xFF0000 is red).

\section{Camera}

The Nao camera object is instantiated by default, under the standard name
\var{camera}. It is deactivated by default, set its \var{load} field to 1 to
activate.

\subsection{Slots}
\begin{itemize}
\item \lstinline|format| \\
  Set the image format: 1 for a jpeg-compressed image, 0 for raw yuv.
\item \lstinline|formatDetail| \\
  Set the image format, providing more options:
  \begin{itemize}
  \item \lstinline|1| raw RGB.
  \item \lstinline|2| raw YUV.
  \item \lstinline|3| JPEG.
  \item \lstinline|4| RGB with a PPM header.
  \item \lstinline|5| YUV422:  YUYV, 2 bytes/pixel.
  \item \lstinline|6| Grey8: gray image, 1 byte/pixel.
  \item \lstinline|7| Grey4: gray image 4 bits/pixel.
  \end{itemize}
  JPEG mode gives the smallest images and uses less bandwidth to access the
  images remotely, but uses more CPU power.
\item \lstinline|quality| \\
  Set JPEG compression quality, from 0 to 100.
\item \lstinline|rate| \\
  Set image frame rate in Hz.
\item \lstinline|resolution| \\
  Set image resolution.  0 gives the max resolution (640x380), 1 divides each
  dimension by two(320x240), 2 divides by four(160x120), 3 by eight(80x60).
\item \lstinline|width| \\
  Image width. Read-only.
\item \lstinline|height| \\
  Image height. Read-only.
\item \lstinline|threaded| \\
  Set to 1 to activate threaded mode, and to 0 to deactivate. This must be set
  before switching load to 1 for the first time. Defaults to 1.
\end{itemize}


\section{Other sensors}

The following sensors are available through a \us variable.
Reading the variable will give the latest available sensor value.

\begin{itemize}
\item \lstinline|sonarL.val|, \lstinline|sonarR.val| \\
    last left and right value from the Sonar module.
\item \lstinline|inertial.val| \\
    name of the position detected by inertial sensors.
\item \lstinline|bumperL.val|, \lstinline|bumperR.val| \\
    Foot bumper, can be 0 or 1.
\item \lstinline|headSensorR.val, headSensorM.val, headSensorF.val| \\
    Head touch sensor segments.
\item \lstinline|accelX.val, accelY.val, accelZ.val| \\
    Accelerometer values.
\item \lstinline|gyroX.val, gyroY.val, gyroZ.val| \\
    Gyroscope values.
\item \lstinline|battery.voltage, battery.current| \\
    Current battery voltage and current usage.
\end{itemize}

\section{Interfacing with \naoqi}

\subsection{Accessing the \naoqi shared memory region}

Many \naoqi modules communicate through a shared hash table handled by
the \lstinline|ALMemory| module. This module is available under the
\lstinline|stm| name in \urbi, and has the following slots:

\begin{itemize}
\item \lstinline|get(\var{name})| \\
  Return the value of memory location \var{name}.
\item \lstinline|set(\var{name}, \var{value})| \\
  Set memory location \var{name} to \var{value}.
\item \lstinline|bindRenameVariable(\var{memoryName}, \var{variableName})| \\
  Create a \us slot named \var{variableName}, and synchronize it with memory
  location \var{memoryName}. Only read support is available.
  \var{variableName} can be of the form "a.b", in which case it will create
  variable "b" in object "a", or of the form "b", in which case variable "b"
  will be created in object "stm".
\end{itemize}

\subsection{Accessing standard \naoqi modules}<commit_msg>doc nao: Bring it up to date.<commit_after>%% Copyright (C) 2009-2010, <NAME>.
%%
%% This software is provided "as is" without warranty of any kind,
%% either expressed or implied, including but not limited to the
%% implied warranties of fitness for a particular purpose.
%%
%% See the LICENSE file for more information.

\newcommand{\naoqi}{NaoQi\xspace}

\chapter{Nao}
\label{sec:nao}

\section{Introduction}

The \dfn{Nao} is a 60 centimeters tall humanoid robot built by
\dfn{Aldebaran} Robotics.  It has an onboard Geode processor running
Linux, 25 degrees of freedom, two onboard cameras, speakers,
microphones, accelerometers, ultrasound and IR sensors...

\section{Starting up}

Nao comes with an installed version of \urbi.

On some versions of Nao, \urbi is not automatically started upon start-up.
If this is the case, you must take the following steps to activate \urbi:

\begin{itemize}
\item Log in to your Nao using ssh: \lstinline|ssh nao@myNao|
\item Add a line containing \lstinline|urbistarter| to
  \file{/opt/naoqi/preferences/autoload.ini}.
\item Restart your Nao.
\end{itemize}

Those lines might already be present but commented out.

You should be able to connect to your Nao on the port 54000 and send it \us:

\begin{urbiunchecked}
tts.say("Hello, I am Nao."),
// Activate right arm.
armR.load = 1;
// Wave the arm: put it in position
shoulderRollR.val = -0.3 time: 0.5s |
shoulderPitchR.val = -1 speed: 0.9 |
// Wave it
timeout(6s) shoulderRollR.val = -0.4 sin:2s ampli:0.4;
// And put it back down, using the uncompressed name this time
robot.body.arm[right].shoulder.pitch.val = 2 speed:0.9;
// Activate all motors.
motors.on;
// Stand
motion.walkTo(0.1,0,0);
// Start walking...
tag: robot.walk(1),
// ... and interrupt the movement
sleep(2s) | tag.stop;
// Get the list of all devices and the interfaces they implement:
robot.dump;
\end{urbiunchecked}

\section{Accessing joints}
All the Nao joints are accessible through their standard Nao and \urbi names,
and respect the \urbi standard specifications for servo motors: Basically each
motor has a \var{load} field that is linked to the motor stiffness, and a
\var{val} field that can be used to read or write the motor position.

Some motor groups are also provided: they can be used exactly as joints,
but any action performed on a group is sent to all the joints that are a
member of this group.

\begin{urbiunchecked}
// Activate all motors
motors.load = 1;
// Or only all the head motors
head.load = 1;
// Move headYaw to 0.8 in one seconds. Since this commands takes
// one second to execute, terminate with a comma to be able
// to send other commands while it executes.
headYaw.val = 0.8 time: 1s,
// Move headPitch to -0.5 as fast as possible.
headPitch.val = -0.5;
// Move headYaw continuously in a sinusoidal trajectory...
tag: headYaw.val = 0 sin:2s ampli:0.5,
// ...and stop the movement
tag.stop;
\end{urbiunchecked}

The two hands are purposefully not included in the 'motors' group.
Although you can control them using the \var{val} slot, it is recommended that
you use the \var{open()} and \var{close()} methods, since they stop the motors
once the movement is finished.

\subsection{Advanced parameters}

\subsubsection{Trajectory generator period}

The trajectory generators will issue write command at a period given by the
\var{System.period} variable. The default is 10ms which is the native period
of \naoqi.

\subsubsection{Motor back-end method}

\urbi can use two different methods to send the joint commands:
\lstinline|DCM::send()|, or \lstinline|ALMotor::setAngle()|.
The mode can be changed by calling \lstinline|motor.setDCMWrite(bool)|.

In \lstinline|setAngle()| mode, each write operation to a joint will
synchronously call the \command{setAngle()} \naoqi method.

In DCM mode, \urbi will set a hook on the DCM update, and send all
commands in this hook using the \command{send()} method.  \urbi will
send commands S milliseconds in the future. S defaults to 50ms, and
can be changed by calling \lstinline|ALMotor.setDCMShift(shiftValue)|.

\subsubsection{Motor command debugging}

The motors implements a debugging mode that can be activated by
calling \lstinline|ALMotor::setTrace(1)|. While activated, it will
write all sent commands to the file \file{/tmp/traj.log}. Each line will
contain the motor number, the command timestamp, and the command
position.  Be careful not to let this feature active while not using
it, as it would quickly fill-up the memory.

\section{Leds}

All Nao's leds and led groups, as defined by \naoqi, are available as
objects in \us. You can set the led values by writing to the slots
\var{val} (intensity between 0 and 1), \var{r}, \var{g}, \var{b}
(color intensity between 0 and 1) or \var{rgb} (RGB value, one byte
each, i.e. 0xFF0000 is red).

\section{Camera}

The Nao camera object is instantiated by default, under the standard name
\var{camera}. It is deactivated by default, set its \var{load} field to 1 to
activate. The default framerate is only 4fps, so you might want to increase it
before activating the camera.

If you wish to use RTP instead of TCP to receive the camera image, you must:
\begin{itemize}
\item load the RTP module in the engine by typing:
\begin{urbiunchecked}
loadModule("urbi/rtp");
\end{urbiunchecked}
\item also load the RTP module with your remote UObject by adding it to your
urbi-launch command line.
\end{itemize}
RTP will then be used automatically.

\subsection{Slots}
\begin{itemize}
\item \lstinline|format| \\
  Set the image format: 1 for a jpeg-compressed image, 0 for raw yuv.
\item \lstinline|formatDetail| \\
  Set the image format, providing more options:
  \begin{itemize}
  \item \lstinline|1| raw RGB.
  \item \lstinline|2| raw YUV.
  \item \lstinline|3| JPEG.
  \item \lstinline|4| RGB with a PPM header.
  \item \lstinline|5| YUV422:  YUYV, 2 bytes/pixel.
  \item \lstinline|6| Grey8: gray image, 1 byte/pixel.
  \item \lstinline|7| Grey4: gray image 4 bits/pixel.
  \end{itemize}
  JPEG mode gives the smallest images and uses less bandwidth to access the
  images remotely, but uses more CPU power.
\item \lstinline|quality| \\
  Set JPEG compression quality, from 0 to 100.
\item \lstinline|rate| \\
  Set image frame rate in Hz.
\item \lstinline|resolution| \\
  Set image resolution.  0 gives the max resolution (640x380), 1 divides each
  dimension by two(320x240), 2 divides by four(160x120), 3 by eight(80x60).
\item \lstinline|width| \\
  Image width. Read-only.
\item \lstinline|height| \\
  Image height. Read-only.
\item \lstinline|threaded| \\
  Set to 1 to activate threaded mode, and to 0 to deactivate. This must be set
  before switching load to 1 for the first time. Defaults to 1.
\end{itemize}

\section{Whole body motion}

The whole body motion component of the \naoqi can be activated by reading and
writing to the \lstinline|pos| slot of both hands. This sets a target
position in cartesian space for the hand. The \naoqi will use its whole body
to try to reach it. Be careful to only ask for reachable positions.

\section{Other sensors}

The following sensors are available through a \us variable.
Reading the variable will give the latest available sensor value.

\begin{itemize}
\item \lstinline|sonarL.val|, \lstinline|sonarR.val| \\
    last left and right value from the Sonar module.
\item \lstinline|inertial.val| \\
    name of the position detected by inertial sensors.
\item \lstinline|bumperL.val|, \lstinline|bumperR.val| \\
    Foot bumper, can be 0 or 1.
\item \lstinline|headSensorR.val, headSensorM.val, headSensorF.val| \\
    Head touch sensor segments.
\item \lstinline|accelX.val, accelY.val, accelZ.val| \\
    Accelerometer values.
\item \lstinline|gyroX.val, gyroY.val| \\
    Gyroscope values.
\item \lstinline|battery.voltage, battery.current| \\
    Current battery voltage and current usage.
\item \lstinline|fsr.val, fsr.left, fsr.right| \\
    1 if both, the left and the right foot are touching the ground, respectively.
\item \lstinline|fsr.leftFootTotalWeight, fsr.rightFootTotalWeight| \\
    Weight under each feet.
\end{itemize}

\section{Interfacing with \naoqi}

\subsection{Accessing the \naoqi shared memory region}

Many \naoqi modules communicate through a shared hash table handled by
the \lstinline|ALMemory| module. This module is available under the
\lstinline|stm| name in \urbi, and has the following slots:

\begin{itemize}
\item \lstinline|get(\var{name})| \\
  Return the value of memory location \var{name}.
\item \lstinline|set(\var{name}, \var{value})| \\
  Set memory location \var{name} to \var{value}.
\item \lstinline|bindRenameVariable(\var{memoryName}, \var{variableName})| \\
  Create a \us slot named \var{variableName}, and synchronize it with memory
  location \var{memoryName}. Only read support is available.
  \var{variableName} can be of the form "a.b", in which case it will create
  variable "b" in object "a", or of the form "b", in which case variable "b"
  will be created in object "stm".
\end{itemize}

\subsection{Accessing standard \naoqi modules}
{'fraction_non_alphanumeric': 0.09701012228658358, 'fraction_numerical': 0.014510561114036627, 'mean_word_length': 3.921393607831846, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 5, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2718903', 'n_tokens_mistral': 5593, 'n_tokens_neox': 5325, 'n_words': 2297}