Locomotion control service

The locomotion control service provides functions of API calling to control the locomotion of devices. As a locomotion control service agent, LocomotionManagerprovides the main API of the locomotion control service, which can be obtained through the RobotContext object.

LocomotionManager locomotionManager = aRobotContext.getSystemService(LocomotionManager.SERVICE);

Cruzr's locomotion control service only provides an API interface for calling the service functions. Due to the differences between different devices, the parameters in the interface itself have no specific units. Cruzr is used as a reference for the speed unit and distance unit in the sample code and interface descriptions in this guide.

Get the list of devices

try {
    LocomotionDevice/* [1] */ locomotionDevice = locomotionManager.getDevice();
} catch (LocomotionDeviceNotFoundException e) {
    e.printStackTrace();
}

[1] LocomotionDevice is the detailed configuration parameter of the mobile device, including:

Attribute getter	Descriptions
LocomotionDevice.id	Device ID
LocomotionDevice.name	Device name
LocomotionDevice.description	Device description
LocomotionDevice.minTurningSpeed	Minimum turning speed, 1 degree per second
LocomotionDevice.maxTurningSpeed	Maximum turning speed, 115 degrees per second
LocomotionDevice.defaultTurningSpeed	Default turning speed, 50 degrees per second
LocomotionDevice.minMovingSpeed	Minimum moving speed, 0.1 meters per second
LocomotionDevice.maxMovingSpeed	Maximum moving speed, 0.8 meters per second
LocomotionDevice.defaultMovingSpeed	Default moving speed, 0.4 meters per second

Control the movement of the device

Configure different parameters to control the device to complete the specified movement or rotation behavior. Locomotion control can be a single task or a series of tasks composed of multiple controls, which will be introduced one by one below.

Control the device to move in a specified direction. To end the movement, the user has to stop it themself. Use the following code to make it move forward at the default speed.

promise /* [1] */ = locomotionManager.moveStraight(0)
    .progress(new ProgressCallback<LocomotionProgress>() {
        @Override
        public void onProgress(LocomotionProgress/* [2] */ locomotionProgress) {
            // There will be multiple callbacks during the movement process
        }
    })
    .done(new DoneCallback<Void>() {
        @Override
        public void onDone(Void aVoid) {
            // Movement completed
        }
    })
    .fail(new FailCallback<LocomotionException>() {
        @Override
        public void onFail(LocomotionException e) {
            // Movement failed
        }
    });

[1]Return the asynchronous object that performs the movement operation, fetches the result and cancels the processing through this object. See Promise for specific usage.

[2] The <span id="LocomotionProgress">LocomotionProgress</span> object ofasynchronous callback describes the progress information of the device’s movement, including:

Constants	Descriptions
LocomotionProgress.PROGRESS_BEGAN	Begin progress
LocomotionProgress.PROGRESS_ENDED	End progress

Control the device to move at a specified speed in a specified direction. To end the movement, the user has to stop it themself. Use the following code to make it move forward at a speed of 0.5 meters per second

promise = locomotionManager.moveStraight(0, 0.5f);

Control the device to move a specified distance in a specified direction. Use the following code to make it move forward five meters at the default speed

promise = locomotionManager.moveStraightBy(0, 5);

Control the device to move a specified distance in a specified direction at a specified speed. Use the following code to make it move forward five meters at a speed of 0.5 meters per second.

promise = locomotionManager.moveStraightBy(0, 5, 0.5f);

Control the device to move a specified distance in a specified direction. Use the following code to make it move forward five meters in three seconds.

 promise = locomotionManager.moveStraightBy(0, 5, 3000);

Control the device to rotate at a specified speed. To end the rotation, the user has to stop it themself. Use the following code to make it rotate at a speed of 30 degrees per second.

promise = locomotionManager.turn(30);

Control the device to rotate in the specified direction. To end the rotation, the user has to stop it themself. Use the following code to make it rotate counterclockwise at the default speed.

 promise = locomotionManager.turn(false);

Control the device to rotate a specified angle. Use the following code to make it rotate 15 degrees at the default speed.

promise = locomotionManager.turnBy(15);

Control the device to rotate a specified angle at a specified speed. Use the following code to make it rotate 15 degrees at a speed of 30 degrees per second.

promise = locomotionManager.turnBy(15, 30f);

Control the device to rotate a specified angle within a specified time. Use the following code to let it rotate 15 degrees in one second.

promise = locomotionManager.turnBy(15, 1000);

Perform the specified action by configuring locomotion parameters. Use the following code to make it move forward five meters in five seconds and rotate 15 degrees at the default speed

LocomotionOption/* [1] */ option = new LocomotionOption.Builder()
    .setDuration(5000)
    .setMovingAngle(0)
    .setMovingDistance(5)
    .setTurningAngle(15)
    .build();

locomotionManager.locomote(option);

[1] The LocomotionOption object is constructed through LocomotionOption.Builder. The construction parameters are described as follows:

Methods	Type	Descriptions	Default value
Builder.constructor()		Construction without parameters
Builder.setMovingAngle(moveAngle)	float	Moving angle	0
Builder.setMovingSpeed(moveSpeed)	float	Moving speed	0
Builder.setMovingDistance(distance)	float	Moving distance	0
Builder.setTurningAngle(turnAngle)	float	Turning angle	0
Builder.setTurningSpeed(turnSpeed)	float	Turning speed	0
Builder.setTurningAxis(axis)	int	Turning axis	0
Builder.setDuration(duration)	long	Execution duration (unit: milliseconds)	0
Builder.setEmergency(emergency)	boolean	Whether it supports emergency stop	true

Perform a serial locomotion control task. Use the following code to make it move five meters at a speed of 0.5 meters per second toward 15 degrees, and then rotate 20 degrees at a speed of 30 degrees per second.

LocomotionOption option1 = new LocomotionOption.Builder()
    .setMovingSpeed(0.5f)
    .setMovingAngle(15)
    .setMovingDistance(5)
    .build();
LocomotionOption option2 = new LocomotionOption.Builder()
    .setTurningSpeed(30)
    .setTurningAngle(20)
    .build();

ArrayList<LocomotionOption> optionSeries = new ArrayList<>();
optionSeries.add(option1);
optionSeries.add(option2);

locomotionManager.locomoteSerially(optionSeries);

Query the movement status of the steering engine. If it returns true, it means that the device is in locomotion.

locomotionManager.isLocomoting();

Regarding the method of locomotionManager.moveStraightBy and the parameter value of the angle, Cruzr 1S currently only supports 0 or 180, which means forward and backward respectively. Do not use other values.

Monitor device movement

Monitor the changes of the device's movement status

LocomotionListener locomotionListener = new LocomotionListener() {
    @Override
    public void onLocomotionChanged(LocomotionProgress/* [1] */ locomotionProgress) {
        // When the locomotion status of the device changes, it will run here.
    }
};

locomotionManager.registerListener(locomotionListener);

[1]For the device's locomotion progress information, please refer to LocomotionProgress

Cancel monitoring the changes of the device's movement status.

locomotionManager.unregisterListener(locomotionListener);