< Previous PageNext Page >

Working with LEDs

This topic describes working with LEDs on the BlackDog device including: understanding the pre-programmed LED states available during the initial programming phase of the device, customizing LED states and setting LED codes.

Initial Programming Phase LEDs

Note: The following LED states are pre-programmed into the BlackDog device and are meant to be used by developers during the initial programming phase of the device. The LED states can be changed using the information in the sections below titled, "Customizing LED States", and "Setting LED Codes".

Provisioning

• Flashing Purple = Bootloader Provisioning
• Throbbing Cyan = Provisioning
• Throbbing Green = Provisioning Completed Successfully
• Flashing Red = Failure in the Provisioning Process

Normal Use

• Throbbing Amber = Boot Up (Caution - don't pull the device out yet)
• Throbbing Cyan = Normal Use
• Flashing Yellow = Shut Down
• Flashing Yellow-Purple = Kernel Panic
• Flashing Red = Problem/ Bad State (may need to re-image the BlackDog device)
  

Note: Flashing happens every 1/2 second.

Customizing LED States

You can use BlackDog LEDs to inform you of events via the hardware device (without displaying a visual cue on a terminal). For example, you can flash a light to indicate when an application contacts a server.

Note: Use LED patterns that are distinguishable by persons with red/green colorblindness.

The realm_mps_led driver accepts commands from the user-space via the ioctl( ) interface. This driver includes a number of LED functions defined for the device.

The realm_mps_led.h contains a number of predefined constants that define many useful LED patterns. These constants provide a number of LED colors and blink intervals you can use to communicate events. This header also defines the following ioctls:

• REALMLED_IOC_GET_CODE. Gets the currently set LED code as a 32-bit unsigned integer (unsigned int).
• REALMLED_IOC_SET_CODE. Sets the LED patterns to the specified code.
• REALMLED_IOC_STROBE. Sends a one-time, short-blink event for the specified color.
• REALMLED_IOC_UNSET_CODE. Resets the LED to its default state (solid white).

Setting LED Codes

An LED code is a 32-bit integer that determines the colors and blinking patterns of the LED. You can use the predefined codes in realm_mps_led.h or compose your own LED codes. You will probably want to use hexadecimal notation to specify the code.

The table below shows the LED code bit field:

The first bit (high order bit) determines whether the LED will throb (1) or blink (0), the second set of bits determine the blink interval, the next four bits determine the number of colors that cycle, and the remaining bits determine the colors for the cycle.

Note: Be aware that LED messages overwrite each other. This means that the last message passed to the ioctl interface is the one in effect. Because of this, you should only use LED patterns to indicate extremely important events or to help you with debugging and that you should disable in production.

The following sections provide more information about LEDs:

• Setting the Blink Interval
• Setting the Number of Colors
• Specifying the Colors
• Throb Bit
• Example
• Setting LEDs from the Command Line

Setting the Blink Interval

Bits [30:28] in the LED code determine the blink interval for the LED. You can choose 0, 1, or 2 to select the following intervals:

• 0 (short) = 100ms.
• 1 (medium) = 500ms
• 2 (long) = 1000ms (1 second)
• 3 (prolonged) = 2000ms (2 seconds)

Setting the Number of Colors

Bits [27:24] set the number of colors that the LED will cycle through. You can specify up to six colors.

Specifying the Colors

The remaining bits [23:0] allow you to specify the colors (in 1/2 byte segments). If you use hexadecimal notation, realm_mps_led.h includes constants that map to the following colors: 0=Black, 1=Red, 2=Green, 3=Yellow, 4=Blue, 5=Purple, 6=Cyan, 7=White.

Throb Bit

When the throb bit is set, the LED will smoothly transition between black and the color specified in bits 4:0. When this bit is not set, the LED will blink, making sharp transitions between colors.

Example

The following C code example shows how you would set the LED to alternately blink red, white, and blue at 1/2 second (500ms) intervals:

int fd = open("/dev/led", O_RDWR);

unsigned int code = 0x13000471;

ioctl(fd, REALM_IOC_SET_CODE, &code);

Setting LEDs from the Command Line

A program is included called realmled that allows you to set the LED from scripts and so forth. You run the program as follows:

• realmled  Gets the currently set code.
• realmled code. Sets the LED to the code.
• realmled -s color. Sends a one-time blink (strobe) to the LED.
• realmled -r. Resets the LED to the default code.

Type realmled --help to view additional help.

Using Advanced LED Controls

For developers who want to use advanced LED controls, there is a sysctl interface that exposes the LED hardware capabilities more completely at /sys/class/misc/realmled. Please see the header comments in drivers/char/realm_mps_led.c for complete description of each control.

Example

Below is an example which sets throbbing from yellow to purple:

realmled 0
cd /sys/class/misc/realmled
# Enable solid red at 1/4 power
echo 1 > r_enable
echo 0 > r_scale
echo 64 > r_offset
# Enable green with a 2-second period from 0 to 1/4 power
echo 1 > g_enable
echo 64 > g_scale
echo 0 > g_offset
echo 2000 > g_period
echo 0 > g_phase
# Enable blue with a 2-second period from 0 to 1/4 power and a 180 degree phase shift
echo 1 > b_enable
echo 64 > b_scale
echo 0 > b_offset
echo 2000 > b_period
echo 512 > b_phase

	< Previous PageNext Page >

		Copyright © Realm Systems, Inc. 2003-2005. All rights reserved.