MqttRobot Configuration

The MqttRobot is configured through a YAML document that defines the MQTT connection parameters, the robot identification, the robot geometry, the motion control parameters and the additional configuration commands sent to the robot during initialization.

The configuration is validated against the mqtt-robot-schema-1.2 JSON schema before the robot instance is created.

Configuration Parameters

Parameter	Type	Required	Default	Description
class	string	Yes	org.mmarini.wheelly.mqtt.MqttRobot	Java class implementing the MQTT robot interface.
brokerUrl	string	No	tcp://localhost:1883	MQTT broker connection URL.
clientId	string	No	Generated automatically	MQTT client identifier.
user	string	Yes	-	MQTT authentication username.
password	string	Yes	-	MQTT authentication password.
robotId	string	Yes	-	MQTT device identifier of the robot controller.
qrDeviceId	string	Yes	-	MQTT device identifier of the QR camera module.
configureTimeout	integer	No	1000	Maximum time in milliseconds allowed for a single robot configuration command.
retryInterval	integer	No	500	Delay in milliseconds before retrying failed operations.
maxRadarDistance	number	Yes	2.0	Maximum radar distance in meters.
lidarFOV	integer	Yes	25	Lidar field of view in degrees.
contactRadius	number	Yes	0.18	Robot collision radius in meters.
cameraFOV	integer	Yes	60	Camera field of view in degrees.
headFOV	integer	No	130	Sensor head maximum rotation angle in degrees.
headX	number	No	0.0	Sensor head X coordinate relative to robot center in meters.
headY	number	No	0.03	Sensor head Y coordinate relative to robot center in meters.
frontLidarDistance	number	No	0.015	Front lidar offset from the head reference point in meters.
rearLidarDistance	number	No	0.015	Rear lidar offset from the head reference point in meters.
cameraDistance	number	No	0.015	Camera offset from the head reference point in meters.
directionRange	integer	No	5	Minimum rotation angle error in degrees.
targetRange	number	No	0.1	Target distance below which the robot stops movement in meters.
maxRotRange	integer	No	30	Rotation range above which maximum rotation speed is used in degrees.
maxRotPps	integer	No	20	Maximum rotation speed in pulses per second.
maxSpeed	integer	No	40	Maximum linear speed in pulses per second.
decelerateDistance	number	No	0.4	Distance where movement deceleration starts in meters.
sendInterval	integer	No	500	Status message interval in milliseconds.
scanInterval	integer	No	500	Lidar scan interval in milliseconds.
config	array	No	Empty	Additional robot configuration commands.

Example Configuration

class: org.mmarini.wheelly.mqtt.MqttRobot

brokerUrl: tcp://localhost:1883
clientId: wheelly-controller

user: robot
password: password

robotId: wheelly
qrDeviceId: camera

configureTimeout: 1000
retryInterval: 500

maxRadarDistance: 2.0
lidarFOV: 25
contactRadius: 0.18

cameraFOV: 60

headFOV: 130
headX: 0.0
headY: 0.03

frontLidarDistance: 0.015
rearLidarDistance: 0.015
cameraDistance: 0.015

targetRange: 0.1
directionRange: 5
maxRotRange: 30

maxRotPps: 20
maxSpeed: 40

decelerateDistance: 0.4

sendInterval: 500
scanInterval: 500

config:
  - asr: 100
    lambdaFactor: 50
    maxPulseInterval: 1000
    delayedInterval: 100
    tau: 500

MQTT Connection Parameters

brokerUrl

Defines the MQTT broker address used to communicate with the robot.

Default value:

tcp://localhost:1883

clientId

Defines the MQTT client identifier.

If omitted, the MQTT library generates a unique identifier automatically.

user

Defines the MQTT authentication username.

This parameter is mandatory.

password

Defines the MQTT authentication password.

This parameter is mandatory.

robotId

Identifies the MQTT device representing the robot controller.

qrDeviceId

Identifies the MQTT device providing QR camera events.

Timing Parameters

configureTimeout

Defines the maximum waiting time for a single configuration command response.

The value is expressed in milliseconds.

Default:

1000

retryInterval

Defines the delay before retrying failed configuration operations.

The value is expressed in milliseconds.

Default:

500

Robot Geometry Parameters

maxRadarDistance

Defines the maximum distance detected by the radar/lidar system.

Default:

2.0 m

lidarFOV

Defines the lidar sensor aperture angle.

Default:

25 degrees

contactRadius

Defines the physical robot radius used for contact detection.

Default:

0.18 m

cameraFOV

Defines the camera viewing angle.

Default:

60 degrees

headX and headY

Define the sensor head position relative to the robot coordinate system.

Default:

headX: 0.0
headY: 0.03

Values are expressed in meters.

frontLidarDistance

Defines the distance of the front lidar sensor from the head reference point.

Default:

0.015 m

rearLidarDistance

Defines the distance of the rear lidar sensor from the head reference point.

Default:

0.015 m

cameraDistance

Defines the distance of the camera sensor from the head reference point.

Default:

0.015 m

Motion Control Parameters

targetRange

Defines the minimum distance from a target before stopping.

Default:

0.1 m

directionRange

Defines the angular error below which rotation is not performed.

Default:

5 degrees

maxRotRange

Defines the angular error above which the maximum rotation speed is applied.

Default:

30 degrees

maxRotPps

Defines the maximum rotation speed.

Default:

20 pulses per second

maxSpeed

Defines the maximum linear speed.

Default:

40 pulses per second

decelerateDistance

Defines the distance before the target where the robot starts reducing speed.

Default:

0.4 m

Sensor Update Parameters

sendInterval

Defines the interval between robot status transmissions.

Default:

500 ms

scanInterval

Defines the lidar scan interval.

Default:

500 ms

Additional Robot Configuration

The config array contains additional commands sent to the robot during initialization.

Each element is converted into a JSON command and transmitted using the MQTT configuration command.

Example:

config:
  - asr: 100
    lambdaFactor: 50
    maxPulseInterval: 1000
    delayedInterval: 100
    tau: 500

Supported parameters:

Parameter	Type	Description
asr	integer	Sensor configuration value.
lambdaFactor	integer	Filtering factor percentage.
maxPulseInterval	integer	Maximum pulse interval.
delayedInterval	integer	Delayed processing interval.
tau	integer	Sensor time constant.

Internal Initialization

During initialization the robot performs the following steps:

1. Validates the YAML document.
2. Reads MQTT connection parameters.
3. Creates the RobotSpec instance.
4. Generates the default motion controller configuration.
5. Adds user-defined configuration commands.
6. Creates MQTT client and remote devices.
7. Connects to the robot.
8. Sends the configuration commands.

After successful initialization the robot is ready to receive commands and publish sensor events.

Validation Rules

The configuration must satisfy the following conditions:

• user must be present.
• password must be present.
• robotId must be present.
• qrDeviceId must be present.
• maxRadarDistance must be greater than zero.
• contactRadius must be greater than zero.
• lidarFOV must be between 1 and 90 degrees.
• cameraFOV must be between 1 and 179 degrees.
• Motion parameters must respect schema limits.
• Additional configuration commands must match the expected structure.

If validation fails, robot creation is aborted with an exception.

Release

Current version: 0.27.0