Skip to content

Rapp API functions

Jump to bottom Edit New page
Maksym Figat edited this page Sep 28, 2015 · 31 revisions

Home | Previous | Next

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

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.

playAudio(std::string file_path, double position, double volume, double balance, bool play_in_loop)

  • Input:

    • std::string file_path - absolute path of the file
    • double position - position in second where the playing should begin
    • double volume - volume requested [0.0 - 1.0]
    • double balance - Stereo panorama requested (-1.0 : left / 1.0 : right / 0.0 : center)
    • bool play_in_loop - true -- play file in loop; false -- play once from given position

  • Output: Success on play audio request.

  • Description: Method which calls ros service rapp_play_audio. It causes nao robot plays audio file.

stopAudio()

  • Output: success on stop audio request.
  • Description: Method stops all files that are currently being played.

wordSpotting(dictionary, size_of_dictionary)

  • Input:

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

  • Output: Detected word or if word was not detected then it returns "Empty"

  • 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.

Audio file is recorded as a file: "/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.

T getParameter(std::string name)

  • Input:

    • name - it is a name of a parameter from ros parameter server

  • Description: Gets a parameter called name from a ros parameter server.

Vision Functions

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

  • Input:
    • cameraId - selects the camera: "top", "bottom"
    • cameraResolution - sets the camera resolution: 3->4VGA,2->VGA,1->QVGA
  • Output:
    • captured image or cv::Mat() if capture failed
  • Description: This function captures the frame from the robots camera. The resolution of the captured image is set to given cameraResolution. The color space is set to kBGRColorSpace.
val res width height
0 QQVGA 160 120
1 QVGA 320 240
2 VGA 640 480
3 4VGA 1280 960
  • 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
  • Input:
    • 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).
  • Input:
    • 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

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/s].

  • Description: Move to StandInit pose, then move with specified velocity. This is a non blocking method.

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. Stiffness of the Head chain is set automatically. This is a blocking method.

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.

moveJoint(string joint_name, float joint_angle);

  • Input:

    • joint_name - name of joint. Names are specified in removeStiffness section.
      Example: LHipRoll, LShoulderRoll, RWristYaw
    • joint_angle - desired angle [rad]

  • Description: Move Nao joint to specified angle. Stiffness of the joint is set automatically. This is a blocking method.

removeStiffness(string joint_name);

  • Input:
    • joint_name - name of joint, chain or whole Body. Names are specified below.
      Example: LHipRoll, LShoulderRoll, Head(it's a chain of HeadYaw and HeadPitch), RArm, Body
  • Description: Remove joint, chain of joints or whole body stiffness.
  • WARNING: Use method very carefully to prevent robot falling down.
Body is ... Head + LArm + LLeg + RLeg + RArm
The chain ... Head LArm LLeg RLeg RArm

involves the

joints ...

 HeadYaw LShoulderPitch LHipYawPitch1 RHipYawPitch1 RShoulderPitch
HeadPitch LShoulderRoll LHipRoll RHipRoll RShoulderRoll
  LElbowYaw LHipPitch RHipPitch RElbowYaw
  LElbowRoll LKneePitch RKneePitch RElbowRoll
  LWristYaw LAnklePitch RAnklePitch RWristYaw
  LHand RAnkleRoll LAnkleRoll RHand
**IMPORTANT!**
**1** - LHipYawPitch and RHipYawPitch share the same motor so they move simultaneously and symmetrically. In case of conflicting orders, LHipYawPitch always takes the priority.

takePredefinedPosture(string posture);

  • Input:
    • posture - name of a predefined posture. List of programmed postures can be found below.
  • Description: Move to a predefined posture. Stiffness of the whole body is set automatically. This is a blocking method.
Stand StandInit StandZero
posture_stand posture_standinit posture_standzero
Crouch Sit SitRelax
posture_crouch posture_sit posture_sitrelax
LyingBelly LyingBack
posture_lyingbelly posture_lyingback

DA Status Functions

DAInit (int argc, char ** argv)

  • Input:

    • argc – parameter needed for node initialization
    • argv – parameter required for node initialization

  • Description: Constructor of class which sends status from dynamic agent to core agent. Constructor after node initialization sends to core agent "Init" as an information of dynamic agent initialization.

sendDAStatus (std::string str)

  • Input:

    • str – a information of an actual dynamic agent status

  • Description: Sends to core agent an actual status of dynamic agent. Dynamic agent receives as a response a core agent status. It updates a class field called ca_status.

getCAStatus ()

  • Description: Returns the value of core agent status field called ca_status.

Home | Previous | Next

Add a custom footer

Home

##1. General structure of RAPP system

##2. Preparation of hardware for RAPP development

Structure of RAPP project repositories on github

Preparation of virtual machine

Preparation of NAO robot

##3. Running the RAPP system

Preparation of core agent

Running core agent on NAO

##3. Testing dynamic agents on virtual machine

Clone this wiki locally