JAUS Description

Derived from the SAE JAUS Manipulator Service Set (AS6057A) document.

This service is the low level interface to a manipulator arm. 

Motion of the arm and percent effort being currently applied is accomplished via JAUS messages.


Primitive Manipulator Service Messages:

Set Joint Effort – This message, sent by the requesting client, allows the user to independently control each joint offered by the platform in an open loop fashion. The sent command states the percentage level of effort that each joint actuator should apply. The range of the level of effort is from -100 to 100 percent. The message will consist of a list of joints(actuators) available on the robot where the first entry in the list represents the first joint and the last entry in the list represents the last joint.


Query Joint Effort – This message requests the robotic platform to reply with a Report Joint Effort message.


Report Joint Effort - This message is used to provide the receiver the percent effort that is currently being applied to the individual manipulator joints. The values to respond with are typically the values provided by the last received Set Joint Effort message.


As the Primitive Manipulator Service inherits an Access Control type service it is required that any set type message(such as Set Joint Effort) be acted upon only if the requesting client is currently in control of the platform that handles the set request.

As the Primitive Manipulator Service inherits a Management type service it is also required that the platform performing manipulator type functionality be in the Managed 'Ready' state in order to act upon any set request message.

Responding to a Query message with a Report message does not require the platform to be in control by the requester nor does it require that the platform be in the 'Ready' managed state.


Basic Implementation

Upon receiving a Set Joint Effort message the platform handing manipulator functionality should perform the following:

  • Check that the requesting client is in control of the platform
  • Check that the platform is in the 'Ready' Managed state
  • Check that the number of joints in the Set Joint Effort message list is the same as the number of joints on the platform
  • Iterate through the list of joints provided by the message and extract the percentage level value from the current joint position in the list
    • Cache the value for this particular joint position for later usage (Query message)
    • Provide the value to a low level hardware interface for this particular joint position


Upon receiving a Query Joint Effort message the platform handing manipulator functionality should perform the following:

  • Create a Report Joint Effort message object
  • Add to the message list each cached joint position effort value, starting with the first joint and ending with the last joint
  • Send the message


OpenJAUS Implementation

The OpenJAUS SDK provides the manipulator_v2_0::PrimitiveManipulator class.

This class has virtual methods related to the setting and reporting of manipulator joint efforts.

        virtual bool setJointEffort(SetJointEffort *setJointEffort)

        virtual ReportJointEffort getReportJointEffort(QueryJointEffort *queryJointEffort)


Upon receiving a Set Joint Effort message the OpenJAUS SDK will check that the requesting client is in control of the platform and that the platform is in the 'Ready' Managed state.

If these conditions are met, the SDK will then call the setJointEffort(SetJointEffort *setJointEffort) method.

The setJointEffort method should be implemented to perform the following:

  • Check that the number of joints in the passed setJointEffort object list is the same as the number of joints on the platform
  • Iterate through the list of joints provided by the message object and extract the percentage level value from the current joint position in the list
    • Cache the value for this particular joint position for later usage (getReportJointEffort(QueryJointEffort *queryJointEffort))
    • Provide the value to a low level hardware interface for this particular joint position


Upon receiving a Query Joint Effort message the OpenJAUS SDK will call the getReportJointEffort(QueryJointEffort *queryJointEffort) method.

The return value (ReportJointEffort) will be used by the SDK to configure and send the Report Joint Effort message.

The getReportJointEffort method should be implemented to perform the following:

  • Create a Report Joint Effort message object
  • Add to the message list each cached joint position effort value, starting with the first joint and ending with the last joint


Example Code (OpenJAUS specific)

For these examples a manipulator with four joints(actuators) will be used.

The examples will presume that there exist some class object that provides methods for hardware control.

hardwareInterface.setJointEffort(uint8 jointPosition, double percentEffort)



Example 1: Setting the Joint Efforts


std::vector<double> jointPositionEffort(4);
const uint8 NUM_OF_JOINTS = 4;

bool setJointEffort(SetJointEffort *setJointEffort)
{
   // The incoming SetJointEffort message will contain a list of records.
   // Each record represents a joint in the manipulator, with first record representing joint 1
   // and the last record representing the last joint (joint 4 in our example).
   
    openjaus::manipulator_v2_0::JointEffortList& list = setJointEffort->getJointEffortList();

    // Incoming message should only contain 4 records
    if (list.size() == NUM_OF_JOINTS )
    {
        std::vector<openjaus::manipulator_v2_0::JointEffortRecord> &records = list.getJointEffortRec();
        for (uint8 i = 0; i < records.size(); ++i)
        {
            jointPositionEffort[i] = records[i].getJointEffort();
            // The values saved to the jointPositionEffort vector is then passed to the hardware interface of the robot that has methods for setting the joint effort
            // These saved values can also be used for reporting the last commanded joint efforts (an incoming QueryJointEffort message)
           hardwareInterface.setJointEffort(i, jointPositionEffort[i]);
        }
    }
    return true;
}


Example 2: Reporting the Joint Effort values in response to a Query Joint Effort message


    std::vector<double> jointPositionEffort(4);
    const uint8 NUM_OF_JOINTS = 4;

ReportJointEffort getReportJointEffort(openjaus::manipulator_v2_0::QueryJointEffort *queryJointEffort)
{
    openjaus::manipulator_v2_0::ReportJointEffort message;

    openjaus::manipulator_v2_0::JointEffortList& list = message.getJointEffortList();
 
    // Create a joint effort record for each joint and add the record to the ReportJointEffort list.
    // The jointPositionEffort vector would have been populated with values by the setJointEffort() method.
    for (uint8 i = 0; i < NUM_OF_JOINTS; ++i)
    {
        openjaus::manipulator_v2_0::JointEffortRecord record;
        record.setJointEffort(jointPositionEffort[i]);
        list.add(record);
    }

    return message;
}