xref: /dragonfly/share/man/man4/led.4 (revision 6ca88057) 
1.\" Copyright (c) 2003 Sergey A. Osokin <osa@FreeBSD.org>
2.\" All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\"    notice, this list of conditions and the following disclaimer.
9.\" 2. Redistributions in binary form must reproduce the above copyright
10.\"    notice, this list of conditions and the following disclaimer in the
11.\"    documentation and/or other materials provided with the distribution.
12.\"
13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND
14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
16.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR BE LIABLE
17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
23.\" SUCH DAMAGE.
24.\"
25.\" $FreeBSD: head/share/man/man4/led.4 267938 2014-06-26 21:46:14Z bapt $
26.\"
27.Dd October 19, 2014
28.Dt LED 4
29.Os
30.Sh NAME
31.Nm led
32.Nd API for manipulating LEDs, lamps and other annunciators
33.Sh SYNOPSIS
34.In dev/misc/led/led.h
35.Pp
36.Fd "typedef void led_t(void *priv, int onoff);"
37.Ft struct cdev *
38.Fn led_create_state "led_t *func" "void *priv" "char const *name" "int state"
39.Ft struct cdev *
40.Fn led_create "led_t *func" "void *priv" "char const *name"
41.Ft void
42.Fn led_destroy "struct cdev *"
43.Sh DESCRIPTION
44The
45.Nm
46driver provides generic support for handling LEDs, lamps and other
47annunciators.
48.Pp
49The hardware driver must supply a function to turn the annunciator on and off
50and the device
51.Fa name
52of the annunciator relative to
53.Pa /dev/led/ .
54The
55.Fa priv
56argument is passed back to this on/off function and can be used however
57the hardware driver sees fit.
58.Pp
59The lamp can be controlled by opening and writing
60.Tn ASCII
61strings to the
62.Pa /dev/led/bla
63device.
64.Pp
65In the following, we will use this special notation to indicate the resulting
66output of the annunciator:
67.Pp
68.Bl -tag -width indent -offset indent -compact
69.It Ic *
70The annunciator is on for 1/10th second.
71.It Ic _
72The annunciator is off for 1/10th second.
73.El
74.Pp
75State can be set directly, and since the change happens immediately,
76it is possible to flash the annunciator with very short periods and
77synchronize it with program events.
78It should be noted that there is a non-trivial overhead, so this may
79not be usable for benchmarking or measuring short intervals.
80.Pp
81.Bl -tag -width indent -offset indent -compact
82.It Ic 0
83Turn the annunciator off immediately.
84.It Ic 1
85Turn the annunciator on immediately.
86.El
87.Pp
88Flashing can be set with a given period.
89The pattern continues endlessly.
90.Pp
91.Bl -tag -width indent -offset indent -compact
92.It Ic f
93_*
94.It Ic f1
95_*
96.It Ic f2
97__**
98.It Ic f3
99___***
100.It ...
101.It Ic f9
102_________*********
103.El
104.Pp
105Three high-level commands are available:
106.Bl -tag -width indent -offset indent
107.It Ic d%d
108Numbers.
109Each digit is blinked out at 1/10th second, zero as ten pulses.
110Between digits a one second pause and after the last
111digit a two second pause after which the sequence is repeated.
112.It Ic s%s
113String.
114This gives full control over the annunciator.
115Letters
116.Ql A
117.No ...
118.Ql J
119turn the annunciator on for from 1/10th to one full
120second.
121Letters
122.Ql a
123.No ...
124.Ql j
125turn the annunciator off for 1/10th
126to one full second.
127Letters
128.Ql u
129and
130.Ql U
131turn the annunciator off and on respectively when the next
132UTC second starts.
133Unless terminated with a
134.Ql \&. ,
135the sequence is immediately repeated.
136.It Ic m%s
137Morse.
138.Pp
139.Bl -tag -width indent -offset indent -compact
140.It Ql \&.
141becomes
142.Ql _*
143.It Ql -
144becomes
145.Sq Li _***
146.It Ql "\ "
147becomes
148.Sq Li __
149.It Ql \en
150becomes
151.Sq Li ____
152.El
153.El
154.Pp
155The sequence is repeated after a one second pause.
156.Sh FILES
157.Bl -tag -width ".Pa /dev/led/*"
158.It Pa /dev/led/*
159.El
160.Sh EXAMPLES
161A
162.Sq Li d12
163flashes the lamp
164.Pp
165.Dl *__________*_*______________________________
166.Pp
167A
168.Sq Li sAaAbBa
169flashes
170.Pp
171.Dl *_*__**_
172.Bd -literal
173/usr/games/morse -l "Soekris rocks" > /dev/led/error
174.Ed
175.Sh SEE ALSO
176.Xr morse 6
177.Sh HISTORY
178The
179.Nm
180driver first appeared in
181.Fx 5.2 .
182.Sh AUTHORS
183.An -nosplit
184This software was written by
185.An Poul-Henning Kamp Aq Mt phk@FreeBSD.org .
186.Pp
187This manual page was written by
188.An Sergey A. Osokin Aq Mt osa@FreeBSD.org
189and
190.An Poul-Henning Kamp Aq Mt phk@FreeBSD.org .
191