<pagebreak>
====== Light-emitting Diode ======

//Necessary knowledge: 
[HW][[en:hardware:homelab:digi]], 
[ELC][[en:electronics:led_resistor]],
[AVR][[en:avr:registers]], [AVR] [[en:avr:io]], 
[LIB][[en:software:homelab:library:bit]], [LIB][[en:software:homelab:library:pin]]//

===== Theory =====

[{{  :examples:digi:led:led_picture.jpg?150|5 mm legged LED}}]

A light-emitting diode is a semiconductor which emits light when forward voltage is applied. The acronym for light-emitting diode is LED. There are different color combination of diodes and the diodes, which can also emit white light. Like a normal diode, the LED has two contacts – anode and cathode. On drawings the anode is marked as “+” and cathode as “-“.

[{{  :examples:digi:led:led_designator.png?150|Schematic symbol of LED and it's polarity}}]

When forward voltage is applied, an LED’s anode is connected to the positive voltage and the cathode to the negative voltage. The voltage of the LED depends on the LED’s color:  longer wavelength (red) ~2 V, shorter wavelength (blue) ~3 V. Usually the power of a LED is no more than a couple of dozen milliwatts, which means electrical current must be in the same range. When applying greater voltage or current a LED may burn out.

If the LEDs are used specially to illuminate, it is wise to use special electronic circuits which would regulate current and voltage suited for LEDs. However LEDs are quite often used as indicators and they are supplied directly from microcontroller’s pins. Since the supply voltage for microcontrollers is usually higher than the voltage for LEDs, there must be a resistor connected into series with the LED, which limits current and creates the necessary voltage drop. Instructions to calculate proper resistor can be found in the electronics chapter.

LEDs are produced in a variety of casings. Most common LEDs with feet have 3 mm or 5 mm diameter round shell and two long metal connector pins. Longer pin is the anode, the shorter one is the cathode. Surface mounted casing LEDs (SMD – Surface Mounted Device) have a T-shaped symbol on the bottom to indicate the polarity, where the roof of T stands for the location of the anode and the pole marks the cathode.

[{{  :examples:digi:led:led_pin_markings.png?200|Polarity of legged and SMD LED's}}]

===== HomeLab Practice =====

The HomeLab controller control module has one single indicator LED, whose anode is connected through resistor to a power supply and the cathode is connected to the controllers pin. In order to switch on and off this LED, LED pin should be defined as the output and set low or high accordingly. Which means if the pin is set high, the LED is turned off and if the pin is set low, the LED is turned on. Basically it would be possible to connect the LED also so that the anode is connected to the pin of microcontroller, and the cathode is connected to the earth (somewhere there has to be a resistor too) – in that case when the pin is set as high, the LED shines and when the pin is set as low the LED is switched off.

All practical examples for the HomeLab kit, LED switching included, use HomeLab’s pin library. Pin library includes data type //pin//, which contains addresses of pin related registers and pin bitmask. If to create a pin type variable in the program and then initialize it by using macro function PIN, the pin can be used freely with this variable (pin) through whole program without being able to use registers.  
Here are 2 example programs, which are doing exactly the same thing, but one is created on the basis of HomeLab’s library, the other is not. The debug LED, led_debug in HomeLab library, has been described as PB7 (HomeLab I & II) and PQ2 (HomeLab III). The Debug LED is physically located in the Controller module.

<code c>
// HomeLab Controller module LED test program, which
// is based on HomeLab library
#include <homelab/pin.h>

// LED pin configuration.
pin led_debug = PIN(Q,2);

// Main program
int main(void)
{
	// Configuring LED pin as an output
	pin_setup_output(led_debug);
		
	// Lighting up LED
	pin_clear(led_debug);	
}
</code>

<code c>
// HomeLab II Controller module LED test program, which
// accesses  registers directly
#include <avr/io.h>

// Main program
int main(void)
{	
	// Configuring LED pin as an output
	DDRB |= (1 << 7);	
		
	// Lighting up LED
	PORTB &= ~(1 << 7);
}
</code>

First example uses pins’ library (//pin.h// file). First a pin-type variable named //debug led// is created in the program, which holds information about LED pin. In the main program this pin will be set as output by using //pin_setup_output// function. After that the pin is set as low by function //pin_clear//. As the result LED will glow. In the second example variables are not used, setting LED output and lighting it will be done by changing port B data direction and output registers values. The reader who knows more about AVR notices, that in both examples there is no need to give command to light LED, because the default output value of the AVR is 0 anyway, but here it is done by the means of correctness.

What is the difference between the use of the library and the registers? The difference is in the comfort – library is easier, because you do not need to know the registers’ names and their effects. Most important benefit of library is adaptability. Using registers, you must change registers’ names and bitmasks through entire program in order to change pin. When using library, it must be done only in the beginning of the program where pin variable is initialized. Using registers has one deceptive advantage – usage of pin is direct and it is not done through program memory and time consuming functions. However, newer AVR-GCC compiler versions are so smart that they transform library’s functions to exactly same direct commands for manipulating registers like it would have been done directly in program. Must be said that compilers can optimize the code only when it deals with constant single variables not with volatile variables that are changing during work and with arrays.

The next program code is partial pin operations library. Its purpose is to explain the procedures with pin variables. It might not be understandable for the beginners as it uses C language pointers which are not covered in this book, but a lot of materials about pointers can be found from books and internet.

<code c>
// Defining the Pins inside the pin struct
// pin name = PIN(PORT LETTER, PIN NUMBER IN PORT);
pin led_green = PIN(H,5);
 
// Configuring pin as output
inline void pin_setup_output(pin pin){
	bitmask_set(*pin.ddr, pin.mask);
}
 
// Setting pin high
inline void pin_set(pin pin){
	bitmask_set(*pin.port, pin.mask);
}
 

// Setting pin low
inline void pin_clear(pin pin){
	bitmask_clear(*pin.port, pin.mask);
}
</code>

In addition to the Controller module, LEDs are also located on the User interface module board. They are connected electrically in the same way as Controller module’s LED, which means cathode is connected to the AVR pin. For more information see the modules hardware guide.
In addition to //pin_set// and //pin_clear// commands one can use //led_on// and //led_off// commands to control LED pins. The following table shows LEDs constants which are described in the library and the corresponding Controller module pins. Green, yellow and red LEDs are located in the user interface module.

^Constant name^Alternative name ^ HomeLab I & II pin^HomeLab III pin^Description^
|led_debug|LED0|PB7|PQ2	|Blue LED on the Controller module|
|led_green|LED1|PC3|PH5| Green LED|
|led_yellow|LED2|PC4|PH4| Yellow LED|
|led_red|LED3|PC5|PH3| Red LED|

HomeLab library based example program which uses LEDs constants looks as follows:

<code c>

// LED test program for HomeLab User interface module
#include <homelab/pin.h>

// Main program
int main(void)
{
	// Configuring LED pins as an output
	pin_setup_output(led_red);
	pin_setup_output(led_yellow);
	pin_setup_output(led_green);	
	
	// Lighting up red and green LED
        led_on(led_red);
	led_on(led_green);
        // Turn off yellow LED
	led_off(led_yellow);
}
</code>