KBDSetLeds

Syntax

#include <revolution/kbd.h>

KBDEc KBDSetLeds (KBDChannel ch, KBDLedState leds);

Arguments

`ch`	Keyboard channel to set.
`leds`	New `KBDLedState` to send to the keyboard.

Return Values

KBDEc Keyboard error code.
KBD_SUCCESS if the call was successful.
KBD_ERR_NOT_INITIALIZED if the library was not initialized.
KBD_ERR_BAD_VALUE if ch or leds is out of range.
KBD_ERR_BUSY if unable to send a LED command to the keyboard.

Description

Sends a LED command to the keyboard on channel ch. The command tells the keyboard to turn on the LEDs specified by leds.

KBDSetLeds is a blocking call, and it cannot be used from within a callback or whenever interrupts are disabled. To set the LEDs when interrupts are disabled, use KBDSetLedsAsync or KBDSetLedsRetry instead.

Because this function sends a message over the USB bus, avoid calling it too frequently; this will prevent flooding of the USB bus. Avoid sending more than 12 LED commands (total for all keyboards) per 1/60 second. Even this amount is excessive and should be avoided.

This function call may fail due to other traffic on the USB bus. If it returns KBD_ERR_BUSY, the LED command was not sent. In this case you must call it again. Because you want the traffic to die down before trying again, you should have a delay between attempts.

This function will always attempt to send the LED command. Any "lazy" setting of a LED state must be done at a higher level.

We recommend KBDSetLedsAsync, because KBDSetLeds will block if the keyboard's ACK fails on the USB bus.

Revision History

2007/10/03 Added a precaution about keyboard ACK.
2007/03/19 Initial version 0.1.