Lighting services

Lighting services provide the ability to API call control device lights. As the lighting service access agent, LightManager object provides the main API of the lighting service, which can be obtained through the RobotContext object.

LightManager lightManager = aRobotContext.getSystemService(LightManager.SERVICE);

Get the list of lights

Get the number of lights on the device and the details of the lights using the following code:

List<LightDevice> /* [1] */ devices = lightManager.getDeviceList();

[1]Light collection, LightDevice is the information of the light, including:

Attribute getter	Descriptions
LightDevice.id	The unique identification of the light
LightDevice.name	The name of the light
LightDevice.description	The description of the light

If you want to find the details of the light by its id, you can use the following code:

try {
    LightDevice lightDevice = lightManager.getDevice("lightId");
} catch (LightNotFoundException e) {
    // Callbback when the detailed information on the light is not found
}

Turn the light on and off

If you want to turn the light on, you can use the following code:

Map<String, Integer> /* [1] */ devices = new HashMap<>();
devices.put("lightId", Color.BLUE);
lightManager.turnOn(devices);

[1]The collection of lights you want to turn on, key is the id of the light, and value is the color displayed after the light is turned on.

If you only want to turn on one light, you can use the following code:

lightManager.turnOn("lightId", Color.BLUE);

If you want to turn the light off, you can use the following code:

List<String> devices = new ArrayList<>();
devices.add("lightId");
lightManager.turnOff(devices);

If you want to turn off multiple lights, but don't want to create a collection, you can use the following code:

lightManager.turnOff("lightId001", "lightId002");

If you only want to turn off one light, you can use the following code:

lightManager.turnOff("lightId");

If you want to know whether the light is on or off, you can use the following code:

boolean isTurnedOn = lightManager.isTurnedOn("lightId");

If the value returned isTurnedOn is true, it means that the light is on.

Change the light color

If you want to change the light color, you can use the following code:

Map<String, Integer> /* [1] */ devices = new HashMap<>();
devices.put("lightId", Color.BLUE);
lightManager.changeColors(devices);

[1]The collection of lights whose color you want to change, key is the id of the light, and value is the color of the light.

If you only want to change the color of one light, you can use the following code:

lightManager.changeColor("lightId", Color.BLUE);

If you want to get the color of the light, you can use the following code:

int color = lightManager.getColor("lightId");

Change the lighting effect

If you want the lights to show some dynamic effects, you can use the following code:

promise /* [2] */  = lightManager.displayEffect("lightId",
    Uri.parse("light://effect/1") /* [1] */)
    .progress(new ProgressCallback<DisplayProgress>() {
        @Override
        public void onProgress(DisplayProgress displayProgress /* [3] */) {
            // Callback the display process of the lighting effect 
        }
    })
    .done(new DoneCallback<Void>() {
        @Override
        public void onDone(Void aVoid) {
            // Callback the lighting effect is displayed
        }
    })
    .fail(new FailCallback<LightException>() {
        @Override
        public void onFail(LightException e) {
            // Callback the lighting effect display goes wrong
        }
    });

[1]The unique identification of the lighting effect to be displayed.

[2]Return the asynchronous object that is waiting to display progress and results. Through the object, you can wait or monitor the progress and results, or cancel the display process. See Promise for specific usage.

[3] The DisplayProgress object of the asynchronous callback describes the progress information of the light effect display, including:

Attribute getter	Descriptions
DisplayProgress.progress	Progress information began: start of display ended: end of display

Through specific options, you can adjust the action of the light display.

DisplayOption /* [1] */ option = new DisplayOption.Builder(
    "lightId",Uri.parse("light://effect/1")).build();
promise = lightManager.displayEffect(option);

[1] The DisplayOption object is built through DisplayOption.Builder, and the instructions are as follows:

Methods	Descriptions	Default value
Builder.constructor(lightId, effectUri)	The id of the light and the unique identifier of the light effect must be imported during construction.
Builder.setSticky(sticky)	Whether the display process is allowed to be interrupted by other threads true: if it is not in operation, it will be interrupted	false
Builder.setLoops(loops)	Number of loop display 0: unlimited	0
Builder.setExtension(extension)	Customized parameters	JsonObjectString.EMPTY_OBJECT

If you want to display multiple lighting effects, you can specify multiple options, which can be achieved in the following two ways:

DisplayOption option1 = new DisplayOption.Builder(
    "lightId001",Uri.parse("light://effect/1")).setLoops(1).build();
DisplayOption option2 = new DisplayOption.Builder(
    "lightId002",Uri.parse("light://effect/2")).setLoops(1).build();
promise = lightManager.displayEffectSerially(option1, option2);

List<DisplayOption> options = new ArrayList<>();
options.add(option1);
options.add(option2);
promise = lightManager.displayEffectSerially(options);

List of lights and light effects

Lights and light effects can be set by constants

Light color	int
red	RED
white	WHITE
blue	BLUE
green	GREEN
orange	ORANGE
yellow	CYAN
purple	PURPLE

Lighting effect	int
breathe	BREATHE
warning	WARNING
Flash once	FLASH_ONE
Flash twice	FLASH_TWO
Bright for 3 seconds	BRIGHT_3_SECOND
Bright infinitely	BRIGHT_INFINITY