Module light: Control Device Lighting

Provides functions to control the device display light as well as the keyboard illumination.

The lighting elements are accessed by their target number. These numbers can be bitwise combined to address more than one target in one call. The targets are:

• const disp1 = 1 Primary display of the device.
• const keyb1 = 2 Primary keyboard of the device.
• const disp2 = 4 Secondary display of the device.
• const keyb2 = 8 Secondary keyboard of the device.

Some devices have more than these light targets. They are addressed by higher bit values like 16, 32, 64, etc.

Even devices with two displays or keyboards may only recognize the primary ones, those actually in use.

Turning lights on or off may not always have the desired effect, as the state of the lights may also depend on environmental lighting or user activity (e.g., displays will get brighter in a bright environment, whereas keyboard lights may be automatically turned on in a dark environment). Furthermore, the states and state changes reported by this module do not necessarily reflect the real state of the light, as it may be a combination of desired state and a light sensor dependent state.

The functions in this module throw ErrNotSupported if a target is not supported, or ErrArgument if any duration exceeds exceeds 2147483 (35 minutes and 47.483 seconds).

• light.blink
• light.off
• light.on
• light.reset
• light.state
• light.targets
• light.wait

light.blink

Blinks the target light(s) of the device for duration milliseconds with intensity intensity. After the duration expires, the light state for target will be changed to whatever state it was before. If duration=null, the light will blink until its state is changed explicitly. onduration indicates the number of milliseconds the light should be on in each cycle, null uses a default value. offduration indicates the number of milliseconds the light should be off in each cycle, null uses a default value. Not all devices support the setting of cycle durations. The intensity must be a value between 1 and 100, or null for the default intensity.

light.off

Switches the target lights off for duration milliseconds. After the duration expires, the light state for target will be changed to whatever state it was before. If duration=null, the light will stay off until its state is changed explicitly. If fade=true, lights will not turn off instantly, but instead smoothly fade-out. Not all devices support fade-out.

light.on

Switches the target lights on for duration milliseconds with intensity intensity. After the duration expires, the light state for target will be changed to whatever state it was before. If duration=null, the light will stay on until its state is changed explicitly. The intensity must be a value between 1 and 100, or null for the default intensity. If fade=true, lights will not turn on instantly, but instead smoothly fade-in. Not all devices support fade-in.

light.reset

Resets all lights to their "normal" state, as imposed by the system.

light.state

Retrieves the current light state. Supports only one single target, as different targets might have different states.

Returns one of the following values:

• const unknown = 0 Signals an error condition.
• const on = 1 The light is on.
• const off = 2 The light is off.
• const blink = 3 The light is blinking.

light.targets

Returns the bit combination of the available light targets.

light.wait

Waits for a state change of any of the lights in targets, and returns true when at least one of these lights changed. If timeout>=0 and timeout milliseconds have passed without a change, false is returned.

Navigation