Actuators

A set of common actuator models is available in the Stonefish library, including the ones specific for the marine robotics. The implemented actuators can be divided into two groups: the joint actuators and the link actuators. Each actuator type is described below to understand its operation and the way to include it in the simulation scenario.

Warning

Actuators can only be created in connection with a definition of a robot, because they have to be attached to a robot’s joint or link.

Common properties

All of the actuators share a few common properties. Each actuator has a name and a type.

Optionally, the user can enable a watchdog timer that will reset the actuator if no new setpoint was received for a specified timeout time. This can be achieved by using the following syntax:

<actuator name="Thruster" type="thruster">
   <!-- thruster definitions here -->
   <watchdog timeout="1.0"/>
</actuator>

sf::Thruster* th = new sf::Thruster(...);
th->setWatchdog(Scalar(1));

Not all of the actuators are going to use the watchdog as it is limited to the ones that have a clear zero state.

Note

In the following sections, description of each specific actuator implementation is accompanied with an example of actuator instantiation through the XML syntax and the C++ code. It is assumed that the XML snippets are located inside the definition of a robot. In case of C++ code, it is assumed that an object sf::Robot* robot = new sf::Robot(...); was created before the actuator definition.

Joint actuators

The joint actuators are attached to the robot’s joints and they apply forces or torques between the links. They share a set of common properties:

  1. Name: unique string

  2. Type: type of the actuator

  3. Joint name: the name of the robot joint that the actuator is attached to

<actuator name="{1}" type="{2}">
   <!-- specific definitions here -->
   <joint name="{3}"/>
</sensor>

Motor

A motor is a simple actuator that applies desired torque to the joint.

<actuator name="Motor" type="motor">
    <joint name="Joint1"/>
</actuator>

#include <Stonefish/actuators/Motor.h>
sf::Motor* motor = new sf::Motor("Motor");
motor->setCommand(1.0);
robot->AddJointActuator(motor, "Joint1");

Servomotor

A servomotor is an electric motor connected with control and power circuits that allow for controlling it in two modes: position or velocity. It is possible to define an initial position of the joint that will be achieved at the beginning of the simulation.

<actuator name="Servo" type="servo">
    <controller position_gain="1.0" velocity_gain="1.0" max_torque="10.0" max_velocity="0.1"/>
    <joint name="Joint1"/>
    <initial position="0.5"/>
</actuator>

#include <Stonefish/actuators/Servo.h>
sf::Servo* srv = new sf::Servo("Servo", 1.0, 0.5, 10.0);
srv->setControlMode(sf::ServoControlMode::POSITION_CTRL);
srv->setMaxVelocity(0.1);
srv->setDesiredPosition(0.5);
robot->AddJointActuator(srv, "Joint1");

Lights

The Stonefish library delivers high quality, physically based rendering, to enable testing of computer vision algorithms on reallistic synthetic images. Lighting is one of the most important components to be considered. The library implements omnidirectional and spot lights, with physically correct illuminance and attenuation model, and multiple options to specify color. The spot lights are created automatically when the user specifies the cone angle. The color can be defined as black body temperature in Kelvins, RGB triplet or HSV triplet. Lights can be attached to any kind of body, as well as directly to the world frame (like vision sensors).

<light name="Omni">
    <specs radius="0.2" illuminance="10000.0"/>
    <color rgb="0.2 0.3 1.0"/>
    <world_transform xyz="1.0 5.0 2.0" rpy="0.0 0.0 0.0"/>
</light>
<light name="Spot">
    <specs radius="0.1" cone_angle="30.0" illuminance="2000.0"/>
    <color temperature="5600.0"/>
    <origin xyz="1.0 0.0 0.0" rpy="0.0 0.0 0.0"/>
    <link name="Link1"/>
</light>

#include <Stonefish/actuators/Light.h>
sf::Light* l1 = new sf::Light("Omni", 0.2, sf::Color::RGB(0.2, 0.3, 1.0), 10000.0);
AddActuator(l1, sf::Transform(sf::IQ(), sf::Vector3(1.0, 5.0, 2.0)));
sf::Light* l2 = new sf::Light("Spot", 0.1, 30.0, sf::Color::BlackBody(5600.0), 2000.0);
robot->AddLinkActuator(l2, "Link1", sf::Transform(sf::IQ(), sf::Vector3(1.0, 0.0, 0.0)));