Webots Reference Manual - chapter 3 - section 12

Webots Reference Manual


3.12 Connector

Derived from Device.

Connector {
  SFString   type                "symmetric"
  SFBool     isLocked            FALSE
  SFBool     autoLock            FALSE
  SFBool     unilateralLock      TRUE
  SFBool     unilateralUnlock    TRUE
  SFFloat    distanceTolerance   0.01  # [0,inf)
  SFFloat    axisTolerance       0.2   # [0,pi)
  SFFloat    rotationTolerance   0.2   # [0,pi)
  SFInt32    numberOfRotations   4
  SFBool     snap                TRUE
  SFFloat    tensileStrength     -1
  SFFloat    shearStrength       -1
}

3.12.1 Description

Connector nodes are used to simulate mechanical docking systems, or any other type of device, that can dynamically create a physical link (or connection) with another device of the same type.

Connector nodes can only connect to other Connector nodes. At any time, each connection involves exactly two Connector nodes (peer to peer). The physical connection between two Connector nodes can be created and destroyed at run time by the robot's controller. The primary idea of Connector nodes is to enable the dynamic reconfiguration of modular robots, but more generally, Connector nodes can be used in any situation where robots need to be attached to other robots.

Connector nodes were designed to simulate various types of docking hardware:

Connectors can be classified into two types, independent of the actual hardware system:

Symmetric connectors, where the two connecting faces are mechanically (and electrically) equivalent. In such cases both connectors are active.

Asymmetric connectors, where the two connecting interfaces are mechanically different. In asymmetric systems there is usually one active and one passive connector.

The detection of the presence of a peer Connector is based on simple distance and angle measurements, and therefore the Connector nodes are a computationally inexpensive way of simulating docking mechanisms.

3.12.2 Field Summary

3.12.3 Connector Axis System

A Connector's axis system is displayed by Webots when the corresponding robot is selected or when Display Axes is checked in Webots Preferences. The z-axis is drawn as a 5 cm blue line, the y-axis (a potential docking rotation) is drawn as a 5 cm red line, and each additional potential docking rotation is displayed as a 4 cm black line. The bounding objects and graphical objects of a Connector should normally be designed such that the docking surface corresponds exactly to xy-plane of the local coordinate system. Furthermore, the Connector's z-axis should be perpendicular to the docking surface and point outward from the robot body. Finally, the bounding objects should allow the superposition of the origin of the coordinate systems. If these design criteria are not met, the Connector nodes will not work properly and may be unable to connect.

connector_axes

Figure 3.6: Connector axis system

To be functional, a Connector node requires the presence of a Physics node in its parent node. But it is not necessary to add a Physics node to the Connector itself.

3.12.4 Connector Functions



NAME

   wb_connector_enable_presence, wb_connector_disable_presence, wb_connector_get_presence - detect the presence of another connector

SYNOPSIS [C++] [Java] [Python] [Matlab]

  #include <webots/connector.h>

  void wb_connector_enable_presence(WbDeviceTag tag, int ms);
  void wb_connector_disable_presence(WbDeviceTag tag);
  int wb_connector_get_presence(WbDeviceTag tag);

DESCRIPTION

The wb_connector_enable_presence() function starts querying the Connector's presence (see definition below) state each ms milliseconds. The wb_connector_disable_presence() function stops querying the Connector's presence. The wb_connector_get_presence() function returns the current presence state of this connector, it returns:

The presence state is defined as the correct positioning of a compatible peer Connector.

Two connectors are in position if they are axis-aligned, rotation-aligned and near enough. To be axis-aligned, the angle between the z-axes of the two connectors must be smaller than the axisTolerance field. To be rotation-aligned, the angle between the y-axis of both Connectors must be within distanceTolerance of one of the possible numberOfRotations subdivisions of 360 degrees. Two Connectors are near enough if the distance between them (measured between the origins of the coordinate systems) is smaller than distanceTolerance.

Two Connectors are compatible if both types are "symmetric" or if one is "active" and the other is "passive". A further requirement for the compatibility is that the model fields of the connectors must be identical. The conditions for detecting presence can be summarized this way:

presence         := in_position AND compatible
compatible       := type_compatible AND model_compatible
type_compatible  := both connectors are "symmetric" OR one connector
                    is "active" AND the other one is "passive"
model_compatible := both models strings are equal
in_position      := near_enough AND axis_aligned AND rotation_aligned
near_enough      := the distance between the connectors < tolerance
axis_aligned     := the angle between the z-axes < tolerance
rotation_aligned := the n-ways rotational angle is within tolerance



NAME

   wb_connector_lock, wb_connector_unlock - create / destroy the physical connection between two connector nodes

SYNOPSIS [C++] [Java] [Python] [Matlab]

  #include <webots/connector.h>

  void wb_connector_lock(WbDeviceTag tag);
  void wb_connector_unlock(WbDeviceTag tag);

DESCRIPTION

The wb_connector_lock() and wb_connector_unlock() functions can be used to set or unset the Connector's locking state (isLocked field) and eventually create or destroy the physical connection between two Connector nodes.

If wb_connector_lock() is invoked while a peer connector is present (see the definition of presence above), a physical link will be created between the two connectors. If both the isLocked and autoLock fields are TRUE, then the physical link will be created automatically as soon as the peer's presence is detected. If wb_connector_lock() succeeds in creating the link, the two connected bodies will keep a constant distance and orientation with respect to each other from this moment on.

If wb_connector_unlock() is invoked while there is a physical link between two Connectors, the link will be destroyed, unless unilateralUnlock is FALSE and the peer connector is still in the isLocked state.

release 7.0.2
Copyright © 2012 Cyberbotics Ltd. All right reserved.