libspicboard-doc

7seg.h
Go to the documentation of this file.
1 #ifndef _7SEG_H
2 #define _7SEG_H
3 
4 #include <stdint.h>
5 
6 #include "check.h"
7 
8 /**
9  * \addtogroup SEG 7seg (Seven Segment Display)
10  *
11  * \brief Controls the two 7-segment displays on the board
12  *
13  * The two 7-segment displays of the SPiCboard share one common
14  * port of the MCU. The two displays can be connected and
15  * disconnected from the port using two transistors. By quickly
16  * and periodically connecting and disconnecting the displays
17  * an observer will not be able to notice when a display is
18  * disabled and both displays can be used apparently simultaneously.
19  *
20  * The module uses the 8-bit <b>Timer 2</b> of the ATmega328PB
21  * to multiplex the two 7-segment displays.
22  *
23  * \note As the timer is used, interrupts must be enabled for the display to work
24  * (if one of the 7 segments seems to be not working
25  * it is quite likely that interrupts are not enabled --
26  * you have to call <tt>sei()</tt> provided by <tt>avr/interrupt.h</tt>!)
27  *
28  * Example code to display "ok":
29  * \code {.c}
30  * #include <avr/interrupt.h>
31  * #include "7seg.h"
32  *
33  * void main(void){
34  * // enable interrupts
35  * sei();
36  * // display "ok"
37  * sb_7seg_showString("ok");
38  * // spin forever
39  * while(1) {};
40  * }
41  * \endcode
42  *
43  * \sa timer.h
44  *
45  * @{
46  * \file 7seg.h
47  * \version \$Rev: 9414 $
48  */
49 
50 /**
51  * \brief Prints a number in the range [-9; 99] on the 7-segment display
52  *
53  * \param nmbr the number to print
54  *
55  * \retval 0 success
56  * \retval -1 nmbr is smaller than -9
57  * \retval -2 nmbr is greater than 99
58  */
59 int8_t sb_7seg_showNumber(int8_t nmbr);
60 
61 /**
62  * \brief Prints the hexadecimal representation of an 8-bit unsigned integer on the 7-segment display
63  *
64  * \param nmbr the number to print
65  *
66  * \retval 0 on success
67  * \retval !0 on error
68  */
69 int8_t sb_7seg_showHexNumber(uint8_t nmbr);
70 
71 /**
72  * \brief Prints a 2 character string on the 7-segment display
73  *
74  * Supported characters are in the group [-_ 0-9A-Za-z] (contains space).
75  * Read <a href="http://en.wikipedia.org/wiki/Seven-segment_display_character_representations">this</a>
76  * article for possible representations of these characters. Two
77  * characters of the set should never have the same representation.
78  * No differentiation is made between upper- and lowercase characters.
79  *
80  * \param str the 0-terminated string
81  *
82  * \retval 0 success
83  * \retval -1 character at position 0 not printable
84  * \retval -2 character at position 1 not printable
85  * \retval -3 both characters not printable
86  * \retval -4 str is an empty string
87  */
88 int8_t sb_7seg_showString(const char *str);
89 
90 /**
91  * \brief Set the LEDs of the 7-segment display manually
92  *
93  * The bitfield contains one bit for each of the 7 segment LEDs of a block.
94  * A set bit enables and a cleared bit disables the corresponding LED.
95  * The most significant bit determines the block:
96  * If set, the first block (tens' place) will be used, if cleared the second block (ones' place)
97  * \image html 7seg.png
98  * For example a value of 0x86 (decimal 134, binary representation: 1000 0110) will enlight the LEDs 1 and 2 of the first block.
99  *
100  * \param mask 8-bit bitfield describing the desired 7 segment display state
101  */
102 void sb_7seg_setMask(uint8_t mask);
103 
104 /**
105  * \brief Disables the 7-segment displays
106  *
107  * Any running alarms are unregistered.
108  */
109 void sb_7seg_disable(void);
110 
111 /** @}*/
112 
113 #endif
114 
sb_7seg_showNumber
int8_t sb_7seg_showNumber(int8_t nmbr)
Prints a number in the range [-9; 99] on the 7-segment display.
sb_7seg_showString
int8_t sb_7seg_showString(const char *str)
Prints a 2 character string on the 7-segment display.
sb_7seg_setMask
void sb_7seg_setMask(uint8_t mask)
Set the LEDs of the 7-segment display manually.
sb_7seg_showHexNumber
int8_t sb_7seg_showHexNumber(uint8_t nmbr)
Prints the hexadecimal representation of an 8-bit unsigned integer on the 7-segment display.
sb_7seg_disable
void sb_7seg_disable(void)
Disables the 7-segment displays.