Rapp API functions

Base: Nao tutorials Prev: Implementation of dynamic agent Next: Adding new task to NAO commands

Rapp API functions

Rapp API functions are functions which can be used for implementation of dynamic agent. They deliver core agent services.

List of RAPP API functions

• Communication Functions
• Vision Functions
• Navigation Functions

---

---

Communication Functions

---

textToSpeech(std::string text);

• Input: string: text

• Output: success on speak request

• Description: Given a text message, the robot says the specified string of characters while using speakers. Uses the default language.

---

textToSpeech(std::string text, std::string language);

• Input: string: text, string: language

• Output: success on speak request

• Description: Given a text message with language flag, the robot says the specified string of characters while using speakers. Uses the given language.

---

wordSpotting(dictionary, size_of_dictionary)

• Input:

  • std::string dictionary[] - database of recognized words
  • int size_of_dictionary - size of the dictionary

• Output: Detected word

• Description: Given small database of recognized words (for example: [Alarm, E-mail, Hazard, Exit] ). It recognizes the words included in the database and returns the word, which was detected with the highest probability.

• Note: User should speak clearly into the microphone located on the front of the robot head. It works for a small dictionary of words.

---

microphoneEnergy(std::string name);

• Input:

  • std::string name - selected microphone ("front", "left", "right")

• Output:

  • int energy - detected energy level

• Description: This function returns the detected energy by the selected microphone.

• Note: Needed for the captureAudio(std::string file_path, float waiting_time, int microphone_energy).

---

captureAudio (int time)

• Input: recording time duration

• Output: std::string audioUrl (audio file path and name)

• Description: Given time duration of the recording and the destination file path, it records the sound from the NAO microphones by the desired time, and saves the file in the ogg extension.

Example of the audio file path: "/home/nao/ws_rapp_applications_nao/nao/data/mail/sounds/rapp_email.ogg"

Note: Required by the ”email sending” behavior.

---

captureAudio(std::string file_path, float waiting_time, int microphone_energy);

• Input:

  • std::string file_path
  • float waiting_time
  • int microphone_energy

• Output: std::string audioUrl (audio file path and name)

• Description: This function records the audio message. Recording stops after a specified time (waiting_time in [s]), if sound with a sufficient energy level (microphone_energy) was not detected during this time (microphone_energy should be > 1700 (noise)). It saves the file in the ogg extension.

Example of the audio file path: "/home/nao/ws_rapp_applications_nao/nao/data/mail/sounds/rapp_email.ogg"

---

voiceRecord(bool startRecording, std::vector &audio_buffer_vector);

• Input:

  • bool startRecording - For starting or stopping the recording of audio message to the buffer
  • std::vector &audio_buffer_vector - audio buffer

• Output: audio_buffer_vector

• Description: Records the audio message to the buffer until the startRecording parameter was set to false.

• Note: The buffer vector may be released after sending.

---

sendEmail (owner_email, owner_password, to_email)

• Input:

  • owner_email - email address from a message will be send
  • owner_password - password to an email given in owner_email
  • to_email - destination email address

• Description: Sends a recorded audio file "/home/nao/ws_rapp_applications_nao/nao/data/mail/sounds/rapp_email.ogg" from owner_email to to_email.

---

---

Vision Functions

---

captureImage(std::string cameraId, int cameraResolution);

• Input:

  • std::string cameraId - selects the camera: "top", "bottom"
  • int cameraResolution - sets the camera resolution: 3->4VGA,2->VGA,1->QVGA

• Output:

  • sensor_msgs::Image

• Description: This function captures the frame from the robot’s camera. The resolution of the captured image is set to given cameraResolution (3->4VGA,2->VGA,1->QVGA). The color space is set to kBGRColorSpace.

• Note: Required by other functions that uses image from NAO camera.

---

setCameraParams(int cameraId, int cameraParameterId, int newValue );

• Input:

  • int cameraId - Camera ID: 0-top, 1-bottom
  • int cameraParameterId - Camera Parameter ID, see Camera parameters
  • int newValue - new parameter value

• Output: success on setCameraParams request

• Description: Modifies camera internal parameter.

---

getTransform(std::string chainName, int space);

• Input:

  • std::string chainName - Name of the item. Could be: any joint or chain or sensor (Use ALMotionProxy::getSensorNames() for the list of sensors supported on your robot).
  • int space - Task frame {FRAME_TORSO = 0, FRAME_WORLD = 1, FRAME_ROBOT = 2}.

• Output:

  • cv::Mat robotToCameraMatrix - Transposition matrix from one frame to another frame

• Description: This function computes the transposition matrix from one frame to another (e.g. from camera frame to robot frame).

---

qrCodeDetection(sensor_msgs::Image &image, zbar::ImageScanner &set_zbar, cv::Mat &robotToCameraMatrix);

• Input:

  • sensor_msgs::Image &image - the RGB image
  • zbar::ImageScanner &set_zbar - a pointer to external function (e.g. in the ZBar library)
  • cv::Mat &robotToCameraMatrix - Transposition matrix from camera frame to robot frame

• Output:

struct QRcodeDetection
{
   bool isQRcodeFound;// success if QR-code was found;
   int numberOfQRcodes;// number of detected QRcodes
   std::vector< cv::Mat > LandmarkInCameraCoordinate;//Transformation matrix from camera to Landmark
   std::vector< cv::Mat > LandmarkInRobotCoordinate;//Transformation matrix from camera to robot
   std::vector<std::string> QRmessage; //vector for messages from QRcodes
}

• Description: Detects the QR-codes with the matrix computation and message decoding.

---

openDoorDetection(std::vectorcv::Mat &LandmarkInRobotCoordinate, std::vectorstd::string &QRmessage);

• Input:

  • std::vectorcv::Mat &LandmarkInRobotCoordinate - Matrix of QR-code in the robot frame
  • std::vectorstd::string &QRmessage - QR-code message

• Output:

struct QRcodeHazardDetection
{
   bool isHazardFound;// success if hazard was found;
   std::vector<double> hazardPosition_x; // in robot coordinate system - x-axis is directed to the front
   std::vector<double> hazardPosition_y; // in robot coordinate system - y-axis is directed to the left
   std::vector<std::string> openedObject; //message from QRcode of an open object
}

• Description: Detects the hazard of an open door, while using QR-codes.

---

---

Navigation Functions

---

MoveTo(float x, float y, float theta);

• Input:

  • x - x-element of the end position in reference to the start position [m]
  • y - y-element of the end position in reference to the start position [m]
  • theta - Angle of the end position in reference to the start position [rad]

• Description: Move of an increment value.

---

MoveVel(float x, float y, float theta);

• Input:
  • x – velocity along X-axis. Use negative values for backward motion [m/s],
  • y – velocity along Y-axis. Use positive values to go to the left [m/s],
  • theta – velocity around Z-axis. Use negative values to turn clockwise [rad].
• Description: Start move with specified velocity.

---

MoveHead(float yaw, float pitch);

• Input:
  • yaw - Head end position in yaw direction [rad]
  • pitch -Head end position in pitch direction [rad]
• Description: Move Nao head to new position.

HeadYaw	HeadPitch Min	HeadPitch Max	HeadYaw	HeadPitch Min	HeadPitch Max

   |<b>(degrees)</b>|          |       |<b>(radians)</b>|       

-119.52|-25.73|18.91| -2.086017 |-0.449073|0.330041 -87.49|-18.91|11.46|-1.526988|-0.330041|0.200015 -62.45|-24.64|17.19|-1.089958|-0.430049|0.300022 -51.74|-27.50|18.91|-0.903033|-0.479965|0.330041 -43.32|-31.40|21.20|-0.756077|-0.548033|0.370010 -27.85|-38.50|24.18|-0.486074|-0.671951|0.422021 0.0|-38.50|29.51| 0.000000|-0.671951|0.515047 27.85|-38.50|24.18| 0.486074|-0.671951|0.422021 43.32|-31.40|21.20| 0.756077|-0.548033|0.370010 51.74|-27.50|18.91| 0.903033|-0.479965|0.330041 62.45|-24.64|17.19| 1.089958|-0.430049|0.300022 87.49|-18.91|11.46| 1.526988|-0.330041|0.200015 119.52|-25.73|18.91| 2.086017|-0.449073|0.330041

---

MoveStop();

• Description: Stop Nao move.