webots controller API（C++）

webots/Accelerometer.hpp

Accelerometer Node可用于模拟加速计设备，如那些常见的广泛应用于移动电子、机器人和游戏输入设备。加速计节点测量1、2或3轴上的加速度和重力引起的反作用力。它可以是用于检测跌落、上/下方向等。

#include <webots/Accelerometer.hpp>
class Accelerometer : public Device {
virtual void enable(int ms);//函数允许用户启用每毫秒的加速度测量
virtual void disable();//关闭加速度计，节省计算时间。
int getSamplingPeriod();//返回wbaccelerometer-enable()函数中给出的周期，如果设备被禁用，则返回0。
const double *getValues() const;
};

#include<webots/accelerometer.h>
void wb_accelerometer_enable (WbDeviceTag tag, int ms); 
void wb_accelerometer_disable (WbDeviceTag tag); 
int wb_accelerometer_get_sampling_period (WbDeviceTag tag); const double * wb_accelerometer_get_values (WbDeviceTag tag);

get_values()函数返回加速度计测量的当前值。这些值是以3D向量的形式返回的，因此只有指数0,1和2是访问矢量的有效参数。矢量的每个元素都代表沿加速计节点相应轴的加速度，用米/秒的平方表示[m/s2]。第一个元素对应x轴，第二个元素对应y轴，依此类推。
加速计在地球重力的静止状态下，将沿着垂直轴显示1 g (9.81 m/s2)。注意，重力可以在 WorldInfo 节点的重力场中指定。要获得仅由运动引起的加速度，必须减去这个偏移量。当没有减去偏移量时，设备在自由落体期间的输出将为零。

Camera.hpp

namespace webots {
  typedef WbCameraRecognitionObject CameraRecognitionObject;

  class Camera : public Device {
  public:
    explicit Camera(const std::string &name) : Device(name) {}  // Use Robot::getCamera() instead
    virtual ~Camera() {}
    virtual void enable(int samplingPeriod); //允许用户启用摄像机每毫秒更新一次。
    virtual void disable();//可以关闭摄像机，节省计算时间。
    int getSamplingPeriod() const;//函数返回wb-camera-enable()函数中给出的周期，如果设备被禁用，则返回0。
    const unsigned char *getImage() const;//读取相机抓取的最后一张图像。图像被编码为三个字节的序列，分别代表像素的红、绿、蓝三个级别。
    int getWidth() const;//返回摄像机图像的宽度
    int getHeight() const;//返回摄像机图像的高度
    double getFov() const;//允许控制器获取摄像机的视场角(fov,field of view)值。
    double getMaxFov() const;
    double getMinFov() const;
    virtual void setFov(double fov);//允许控制器设置摄像机的视场角,只有当摄像机设备的zoom field定义了 CameraZoom 节点时才有可能
    double getFocalLength() const;//允许控制器获取和设置聚焦参数。
//请注意，如果摄像机设备在其聚焦场中没有定义Focus节点，则无法调用wb_camera_set_focal_distance函数，其他函数将返回0。
    double getFocalDistance() const;
    double getMaxFocalDistance() const;
    double getMinFocalDistance() const;
    virtual void setFocalDistance(double focalDistance);
    double getNear() const;//返回摄像机设备的附近参数
    int saveImage(const std::string &filename, int quality) const;
    /*允许用户保存之前用wb-camera get-image()函数获得的标签图像。
    图像被保存在一个PNG或JPEG格式的文件中。图像格式由 filename 参数指定。
    如果文件名以. png结尾，则图像格式为PNG。如果文件名以 jpg 或 jpeg 结尾，则图像格式为 JPEG。不支持其他图像格式。
    质量参数只对JPEG图像有用。它定义了保存图像的JPEG质量。质量参数应该在1（最差质量）到100（最佳质量）的范围内。
低质量的JPEG文件将使用较少的磁盘空间。对于PNG图像，质量参数被忽略。
如果成功的话，wb came ra-save-image()的返回值为0。如果失败(无法打开指定的文件或无法识别图像文件扩展名)，则返回值为-1。*/
    bool hasRecognition() const;
    void recognitionEnable(int samplingPeriod);
    void recognitionDisable();
    int getRecognitionSamplingPeriod() const;
    int getRecognitionNumberOfObjects() const;
    const CameraRecognitionObject *getRecognitionObjects() const;
    static unsigned char imageGetRed(const unsigned char *image, int width, int x, int y);//直接从像素坐标中获取像素的RGB级别
    static unsigned char imageGetGreen(const unsigned char *image, int width, int x, int y);//直接从像素坐标中获取像素的RGB级别
    static unsigned char imageGetBlue(const unsigned char *image, int width, int x, int y);//直接从像素坐标中获取像素的RGB级别
    static unsigned char imageGetGray(const unsigned char *image, int width, int x, int y);//通过对三个RGB分量的平均来返回指定像素的灰度级别。
    // alias
    static unsigned char imageGetGrey(const unsigned char *image, int width, int x, int y);
  };
}  // namespace webots
#endif  // CAMERA_HPP

Gyro.hpp(陀螺仪)

陀螺仪节点用于模拟1、2、3轴角速度传感器（陀螺仪）。角速度的测量单位是弧度/秒[rad/s]。

namespace webots {
  class Gyro : public Device {
  public:
    explicit Gyro(const std::string &name) : Device(name) {}  // Use Robot::getGyro() instead
    virtual ~Gyro() {}
    virtual void enable(int samplingPeriod);//每samplingPeriod ms开启一次角速度测量
    virtual void disable();//关闭陀螺仪
    int getSamplingPeriod() const;//返回wb-gyro-enable()函数中给出的周期，如果设备被禁用，则返回0。
    const double *getValues() const;
    /*返回当前陀螺仪的测量值,这些值是以3D向量的形式返回的，
    因此只有0、1和2这几个指数可以有效地访问这个向量。
    每一个向量元素代表Gy ro节点的一个轴的角速度，用弧度/秒表示。
    第一个元素对应于x轴的角速度，第二个元素对应于y轴的角速度，等等。*/
  };
}  // namespace webots

LED.hpp

namespace webots {
  class LED : public Device {
  public:
    explicit LED(const std::string &name) : Device(name) {}  // Use Robot::getLED() instead
    virtual ~LED() {}
    virtual void set(int value);//可以打开或关闭一个LED灯，并可能改变其颜色。如果参数值为0，则LED被关闭。否则，LED将被打开。
    /*
    在非渐变LED(渐变字段设置为FALSE)的情况下，如果参数值为1，则使用相应LED节点的co lor字段中指定的第一个颜色打开LED。如果参数值为2，则使用LED节点颜色字段中指定的第二种颜色打开LED，以此类推。参数值不应大于相应LED节点的颜色域的大小，如果参数值为2，则使用LED节点颜色域中指定的第二种颜色打开LED，以此类推。
如果是单色LED(渐变域设置为TRUE，色域正好包含一种颜色)，数值参数表示LED的强度，范围为0(关闭)至25(最大强度)。
如果是RGB LED(渐变字段设置为TRUE，颜色字段为空)，数值参数表示LED的RGB颜色，范围为0(关闭或黑色)到Oxffffff(白色)。格式为R8G8B8：最重要的8位(左手边)表示红色级别(Ox00和Oxff之间)。R8G8B8：最重要的8位(左手边)表示红色电平(在Ox00和Oxff之间)，8到15位表示绿色电平，最不重要的8位(右手边)表示蓝色电平。例如，Oxff0000为红色，0x00ff00为绿色，0x0000ff为蓝色，Oxffff00为黄色，等等。
    */
    int get() const;//返回上一次调用wb_led_set函数时的参数值。
  };
}  // namespace webots

Device.hpp

namespace webots {
  class Device {
  public:
    virtual ~Device() {}
    const std::string &getName() const { return name; }//作为参数（tag）给定的WbDeviceTag转换为相应的名称。
    std::string getModel() const;//返回相应设备的型号字符串,如果WbDeviceTag不符合一个有效的设备，这个函数返回NULL，如果设备不是一个实体设备（即没有模型字段），则返回一个空字符串。
    int getNodeType() const;//将作为参数(tag)给出的WbDeviceTag转换为其对应的WbNodeType(参考Supervisor API)。如果WbDeviceTag与有效设备不匹配，该函数返回NULL。
    int getTag() const { return tag; }

    static bool hasType(int tag, int type);

  protected:
    explicit Device(const std::string &name);

  private:
    WbDeviceTag tag;
    std::string name;
  };
}  // namespace webots

Motor.hpp

电机节点是一个抽象节点（未实例化），其派生类是RotationalMotor和LinearMotor。这些类可以在机械模拟中用来驱动一个关节，从而产生一个沿着或围绕其轴的运动。

一个RotationalMotor可以为一个HingeJoint（或Hinge2Joint）提供动力，当设置在这些节点的设备（或设备或设备2）领域内。
它就会产生一个围绕所选轴线的旋转运动。
同样，LinearMotor也可以为SliderJoint提供动力，产生一个沿其轴线的滑动运动。

namespace webots {
  class Brake;
  class PositionSensor;

  class Motor : public Device {
  public:
    typedef enum { ROTATIONAL = 0, LINEAR } Type;

    explicit Motor(const std::string &name) :
      Device(name),
      brake(NULL),
      positionSensor(NULL) {}  // Use Robot::getMotor() instead
    virtual ~Motor() {}

    virtual void setPosition(double position);//指定一个目标位置，然后PID控制器将使用当前的速度、加速度和电机转矩/力参数试图达到这个位置。
    //INFINITY值可以作为wb_motor_set_position函数的第二个参数，以实现无止境的旋转（或线性）运动,wb_motor_set_velocity函数可以用来控制无止境旋转的速度
    virtual void setVelocity(double vel);//指定了电机移动到目标位置时应该达到的速度。
    //对于旋转电机来说，速度的单位是弧度/秒[rad/s]，对于线性电机来说，速度的单位是米/秒[m/s]。换句话说，这意味着电机将加速（使用指定的加速度，见下文），直到达到目标速度。不能超过maxVelocity字段中指定的限制
    //请注意，如果没有使用 wb_motor_set_velocity 函数明确设置速度，那么 wb_motor_get_velocity 和 wb_motor_get_max_velocity 函数返回相同的值。
    virtual void setAcceleration(double acceleration);//指定了PID控制器在试图达到指定速度时应该使用的加速度。
    //对于旋转电机，加速度的单位是弧度/秒平方[rad/s²]，对于直线电机，加速度的单位是米/秒平方[m/s²]。请注意，通过传递-1作为该函数的acc参数，可以得到无限的加速度。
    virtual void setAvailableForce(double availableForce);//指定了电机在执行要求的运动时可以使用的最大力
    virtual void setAvailableTorque(double availableTorque);
    virtual void setControlPID(double p, double i, double d);//改变PID控制器中的增益P、I和D的值。
    //这些参数用于从当前位置Pc和目标位置Pt计算当前电机速度Vc，使得Vc其中误差=Ptc。如果P小，则需要很长的时间才能达到目标位置，而P过大则会使系统不稳定。

    double getTargetPosition() const;//允许用户获得目标位置。这个值与上一次调用 wb_motor_set_position 函数时的参数相匹配。
    double getMinPosition() const;
    double getMaxPosition() const;
    double getVelocity() const;
    double getMaxVelocity() const;
    double getAcceleration() const;
    double getAvailableForce() const;
    double getMaxForce() const;
    double getAvailableTorque() const;
    double getMaxTorque() const;

    virtual void enableForceFeedback(int samplingPeriod);//函数激活指定电机的力（或扭矩）反馈测量。sampling_period参数指定了传感器的采样周期，以毫秒为单位。请注意，只有在第一个采样周期结束后，才可以进行第一次测量。
    virtual void disableForceFeedback();
    int getForceFeedbackSamplingPeriod() const;
    double getForceFeedback() const;//返回最近的电机力（或扭矩）测量值。该函数测量电机当前为实现所需运动或保持当前位置而使用的电机力(力矩)的大小。

    virtual void enableTorqueFeedback(int samplingPeriod);
    virtual void disableTorqueFeedback();
    int getTorqueFeedbackSamplingPeriod() const;
    double getTorqueFeedback() const;

    virtual void setForce(double force);//指定了所需的力（或扭矩）并关闭了 PID 控制器.指定的力 (resp. torque) 会连续地施加到电机上。
//因此，除非使用功能性的力控制(或扭矩控制)算法，否则电机将无限加速其旋转或线性运动，并最终爆炸。
    virtual void setTorque(double torque);

    Type getType() const;//允许用户检索由类型字段定义的电机类型，如果类型字段的值是 "线性"，则该函数返回WB_LINEAR，否则返回WB_ROTATIONAL。

    Brake *getBrake();//返回定义在同一个关节或轨道设备字段中的刹车。
    PositionSensor *getPositionSensor();//返回定义在同一个关节或轨道设备字段中的位置传感器实例。

    // internal functions
    int getBrakeTag() const;
    int getPositionSensorTag() const;

  private:
    Brake *brake;
    PositionSensor *positionSensor;
  };
}  // namespace webots

PositionSensor.hpp

namespace webots {
  class Brake;
  class Motor;

  class PositionSensor : public Device {
  public:
    typedef enum { ROTATIONAL = 0, LINEAR } Type;

    explicit PositionSensor(const std::string &name) :
      Device(name),
      brake(NULL),
      motor(NULL) {}  // Use Robot::getPositionSensor() instead
    virtual ~PositionSensor() {}
    virtual void enable(int samplingPeriod);  // milliseconds,启用关节位置的测量
    virtual void disable();
    int getSamplingPeriod() const;//函数返回给 wb_position_sensor_enable 函数的周期，如果设备被禁用，则返回 0。
    double getValue() const;  // rad or meters//返回指定位置传感器测量的最新值。根据不同的类型，它将以弧度[rad]（角度位置传感器）或以米[m]（线性位置传感器）为单位返回值。
    Type getType() const;//返回位置传感器的类型。
//如果传感器与HingeJoint或Hinge2Joint节点相关联，则返回WB_ROTATIONAL，如果与SliderJoint或Track节点相关联，则返回WB_LINEAR。

    Brake *getBrake();//返回定义在同一个[Joint](joint.md)或[Track](track.md)`device`字段中的[Brake](brake.md)和[Motor](motor.md)实例。如果没有定义，则返回0。
    Motor *getMotor();

    // internal functions
    int getBrakeTag() const;
    int getMotorTag() const;

    enum {  // kept for backward compatibility R2018b
      ANGULAR = 0
    };

  private:
    Brake *brake;
    Motor *motor;
  };
}  // namespace webots

Keyboard.hpp

键盘不是一个节点，它是一组函数，默认情况下，每个机器人节点都可以读取键盘输入。
因此，它不是一个设备，功能不需要任何WbDeviceTag。

namespace webots {
  class Keyboard {
  public:
    enum {
      END = 312,
      HOME,
      LEFT,
      UP,
      RIGHT,
      DOWN,
      PAGEUP = 366,
      PAGEDOWN,
      NUMPAD_HOME = 375,
      NUMPAD_LEFT,
      NUMPAD_UP,
      NUMPAD_RIGHT,
      NUMPAD_DOWN,
      NUMPAD_END = 382,
      KEY = 0x0000ffff,
      SHIFT = 0x00010000,
      CONTROL = 0x00020000,
      ALT = 0x00040000
    };

    Keyboard() {}  // Use Robot::getKeyboard() instead
    virtual ~Keyboard() {}
    virtual void enable(int samplingPeriod);//启用键盘输入，sampling_period参数以毫秒为单位，定义了读数更新的频率。
    virtual void disable();//停止键盘读数
    int getSamplingPeriod() const;
    int getKey() const;//读取值，返回的值如果是非负值，则是当前按下的键对应的键码。
    /*如果没有修饰键（shift、control或alt）被按下，则键码是对应键的ASCII码或一个特殊值（例如，对于方向键）。
然而，如果一个修饰键被按下，ASCII码（或特殊值）可以通过在WB_KEYBOARD_KEY掩码和返回值之间应用二进制AND来获得。
在这种情况下，返回值是在WB_KEYBOARD_SHIFT、WB_KEYBOARD_CONTROL或WB_KEYBOARD_ALT中的一个键和被按下的键的ASCII码(或特殊值)之间的二进制OR的结果，根据哪个修改键被同时按下。
如果当前没有按键被按下，函数将返回-1。
第二次调用wb_keyboard_get_key函数将返回-1或当前同时按下的另一个键的键码。
这个函数最多可以被调用7次，以检测到7个同时被按下的键。*/
  };
}  // namespace webots

Speaker.hpp

扬声器节点代表了一个扬声器设备，可以嵌入到机器人上或站在环境中。
它可以用来播放声音，并从控制器API执行文本到语音。

namespace webots {
  class Speaker : public Device {
  public:
    explicit Speaker(const std::string &name) : Device(name) {}  // Use Robot::getSpeaker() instead
    virtual ~Speaker() {}
    static void playSound(Speaker *left, Speaker *right, const std::string &sound, double volume, double pitch, double balance,
                          bool loop);
    /*
    此功能可以让用户播放声音文件，支持所有主要的音频格式，如MP3、AIFF、AAC、WAV、FLAC和OGG Vorbis。
支持所有主要的音频格式，如MP3、AIFF、AAC、WAV、FLAC和OGG Vorbis。
volume参数允许用户指定这个声音的音量（在0.0和1.0之间）。
pitch参数允许用户修改声音的音高，默认的声音音高乘以 pitch参数。pitch参数应该是正数。值为1.0表示不改变音高。
平衡参数允许用户指定左右扬声器之间的平衡（在-1.0和1.0之间）。值为0表示没有平衡：两个通道的音量相同。值为-1.0表示右声道静音。值为1.0表示左声道静音。中间值定义了左声道和右声道之间的音量差异。
最后，loop参数定义了声音是只播放一次还是重复播放。
    */
    bool isSoundPlaying(const std::string &sound) const;//用来检查给定的声音是否正在播放。可以通过将sound设置为NULL（或在面向对象的API中设置为空字符串）来检查扬声器是否在播放任何声音（包括文本到语音）。
    void stop(const std::string &sound);//停止特定的声音。可以通过将sound设置为NULL来停止当前在扬声器中播放的所有声音。
    bool setEngine(const std::string &engine);//允许用户设置扬声器要使用的文本到语音引擎。
    bool setLanguage(const std::string &language);//允许用户设置当前文本到语音引擎的语言。
    /*
"en-US "代表美国英语（默认值）。
"en-UK "代表英式英语。
"de-DE "代表德语。
"es-ES "代表西班牙语。
"fr-FR "代表法语。
"it-IT "代表意大利语。
    */
    std::string getEngine();//允许用户获取扬声器设备的文本到语音引擎。
    std::string getLanguage();//允许用户获取扬声器设备的文本到语音的语言。
    void speak(const std::string &text, double volume);//允许用户在扬声器上执行文本到语音。
    bool isSpeaking() const;//如果扬声器当前正在执行文本到语音，返回True。例如，在开始新的句子之前，它可以用来检查前一句话是否已经结束。
  };
}  // namespace webots