The fiducial interface provides access to devices that detect coded fiducials (markers) placed in the environment.
| #define PLAYER_FIDUCIAL_MAX_SAMPLES 32 |
The maximum number of fiducials that can be detected at one time.
| #define PLAYER_FIDUCIAL_MAX_MSG_LEN 32 |
The maximum size of a data packet exchanged with a fiducial at one time.
|
#define PLAYER_FIDUCIAL_GET_GEOM 0x01
#define PLAYER_FIDUCIAL_GET_FOV 0x02 #define PLAYER_FIDUCIAL_SET_FOV 0x03 #define PLAYER_FIDUCIAL_SEND_MSG 0x04 #define PLAYER_FIDUCIAL_RECV_MSG 0x05 #define PLAYER_FIDUCIAL_EXCHANGE_MSG 0x06 |
Request packet subtypes
The fiducial data packet contains a list of the detected fiducials. Each fiducial is described by the player_fiducial_item structure listed below.
struct player_fiducial_item : The fiducial data packet (one fiducial).
| int16_t id; |
The fiducial id. Fiducials that cannot be identified get id -1.
| int16_t pose[3]; |
Fiducial pose relative to the detector (range, bearing, orient) in units (mm, degrees, degrees).
| int16_t upose[3]; |
Uncertainty in the measured pose (range, bearing, orient) in units of (mm, degrees, degrees).
struct player_fiducial_data : The fiducial data packet (all fiducials).
| uint16_t count; |
The number of detected fiducials
| player_fiducial_item_t fiducials[PLAYER_FIDUCIAL_MAX_SAMPLES]; |
List of detected fiducials
This device accepts no commands.
The geometry (pose and size) of the fiducial device can be queried using the PLAYER_FIDUCIAL_GET_GEOM request. The request and reply packets have the same format.
struct player_fiducial_geom : Fiducial geometry packet.
| uint8_t subtype; |
Packet subtype. Must be PLAYER_FIDUCIAL_GET_GEOM.
| uint16_t pose[3]; |
Pose of the detector in the robot cs (x, y, orient) in units if (mm, mm, degrees).
| uint16_t size[2]; |
Size of the detector in units of (mm, mm)
| uint16_t fiducial_size[2]; |
Dimensions of the fiducials in units of (mm, mm).
The field of view of the fiducial device can be set using the PLAYER_FIDUCIAL_SET_FOV request, and queried using the PLAYER_FIDUCIAL_GET_FOV request. The device replies to a SET request with the actual FOV achieved. In both cases the request and reply packets have the same format.
struct player_fiducial_fov : Fiducial geometry packet.
| uint8_t subtype; |
Packet subtype. PLAYER_FIDUCIAL_GET_FOV or PLAYER_FIDUCIAL_SET_FOV.
| uint16_t min_range; |
The minimum range of the sensor in mm
| uint16_t max_range; |
The maximum range of the sensor in mm
| uint16_t view_angle; |
The receptive angle of the sensor in degrees.
NOTE: These configs are currently supported only by the Stage fiducial driver (stg_fidicial), but are intended to be a general interface for addressable, peer-to-peer messaging.
The fiducial sensor can attempt to send a message to a target using the PLAYER_FIDUCIAL_SEND_MSG request. If target_id is -1, the message is broadcast to all targets. The device replies with an ACK if the message was sent OK, but receipt by the target is not guaranteed. The intensity field sets a transmit power in device-dependent units. If the consume flag is set, the message is transmitted just once. If it is unset, the message may transmitted repeatedly (at device-dependent intervals, if at all).
Send a PLAYER_FIDUCIAL_RECV_MSG request to obtain the last message recieved from the indicated target. If the consume flag is set, the message is deleted from the device's buffer, if unset, the same message can be retreived multiple times until a new message arrives. The power field indicates the intensity of the recieved messag, again in device-dependent units.
Similarly, the PLAYER_FIDUCIAL_EXCHANGE_MSG request sends a message, then returns the most recently received message. Depending on the device and the situation, this could be a reflection of the sent message, a reply from the target of the sent message, or a message received from an unrelated sender.
Fiducial exchange mesaage request. The device sends the message, then replies with the last message received, which may be (but is not guaranteed to be) be a reply to the sent message. NOTE: this is not yet supported by Stage-1.4.