share/man/man4/led.4

   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$
  26 .\"
  27 .Dd May 29, 2005
  28 .Dt LED 4
  29 .Os
  30 .Sh NAME
  31 .Nm led
  32 .Nd API for manipulating LED's, lamps and other annunciators
  33 .Sh SYNOPSIS
  34 .In dev/led/led.h
  35 .Pp
  36 .Fd "typedef void led_t(void *priv, int onoff);"
  37 .Ft struct cdev *
  38 .Fn led_create "led_t *func" "void *priv" "char const *name"
  39 .Ft void
  40 .Fn led_destroy "struct cdev *"
  41 .Sh DESCRIPTION
  42 The
  43 .Nm
  44 driver provides generic support for handling LEDs, lamps and other
  45 annunciators.
  46 .Pp
  47 The hardware driver must supply a function to turn the annunciator on and off
  48 and the device
  49 .Fa name
  50 of the annunciator relative to
  51 .Pa /dev/led/ .
  52 The
  53 .Fa priv
  54 argument is passed back to this on/off function and can be used however
  55 the hardware driver sees fit.
  56 .Pp
  57 The lamp can be controlled by opening and writing
  58 .Tn ASCII
  59 strings to the
  60 .Pa /dev/led/bla
  61 device.
  62 .Pp
  63 In the following, we will use this special notation to indicate the resulting
  64 output of the annunciator:
  65 .Pp
  66 .Bl -tag -width indent -offset indent -compact
  67 .It Ic *
  68 The annunciator is on for 1/10th second.
  69 .It Ic _
  70 The annunciator is off for 1/10th second.
  71 .El
  72 .Pp
  73 State can be set directly, and since the change happens immediately,
  74 it is possible to flash the annunciator with very short periods and
  75 synchronize it with program events.
  76 It should be noted that there is a non-trivial overhead, so this may
  77 not be usable for benchmarking or measuring short intervals.
  78 .Pp
  79 .Bl -tag -width indent -offset indent -compact
  80 .It Ic 0
  81 Turn the annunciator off immediately.
  82 .It Ic 1
  83 Turn the annunciator on immediately.
  84 .El
  85 .Pp
  86 Flashing can be set with a given period.
  87 The pattern continues endlessly.
  88 .Pp
  89 .Bl -tag -width indent -offset indent -compact
  90 .It Ic f
  91 _*
  92 .It Ic f1
  93 _*
  94 .It Ic f2
  95 __**
  96 .It Ic f3
  97 ___***
  98 .It ...
  99 .It Ic f9
 100 _________*********
 101 .El
 102 .Pp
 103 Three high-level commands are available:
 104 .Bl -tag -width indent -offset indent
 105 .It Ic d%d
 106 Numbers.
 107 Each digit is blinked out at 1/10th second, zero as ten pulses.
 108 Between digits a one second pause and after the last
 109 digit a two second pause after which the sequence is repeated.
 110 .It Ic s%s
 111 String.
 112 This gives full control over the annunciator.
 113 Letters
 114 .Ql A
 115 .No ...
 116 .Ql J
 117 turn the annunciator on for from 1/10th to one full
 118 second.
 119 Letters
 120 .Ql a
 121 .No ...
 122 .Ql j
 123 turn the annunciator off for 1/10th
 124 to one full second.
 125 Letters
 126 .Ql u
 127 and
 128 .Ql U
 129 turn the annunciator off and on respectively when the next
 130 UTC second starts.
 131 Unless terminated with a
 132 .Ql \&. ,
 133 the sequence is immediately repeated.
 134 .It Ic m%s
 135 Morse.
 136 .Pp
 137 .Bl -tag -width indent -offset indent -compact
 138 .It Ql \&.
 139 becomes
 140 .Ql _*
 141 .It Ql -
 142 becomes
 143 .Sq Li _***
 144 .It Ql "\ "
 145 becomes
 146 .Sq Li __
 147 .It Ql \en
 148 becomes
 149 .Sq Li ____
 150 .El
 151 .El
 152 .Pp
 153 The sequence is repeated after a one second pause.
 154 .Sh FILES
 155 .Bl -tag -width ".Pa /dev/led/*"
 156 .It Pa /dev/led/*
 157 .El
 158 .Sh EXAMPLES
 159 A
 160 .Sq Li d12
 161 flashes the lamp
 162 .Pp
 163 .Dl *__________*_*______________________________
 164 .Pp
 165 A
 166 .Sq Li sAaAbBa
 167 flashes
 168 .Pp
 169 .Dl *_*__**_
 170 .Pp
 171 .Bd -literal
 172 /usr/games/morse -l "Soekris rocks" > /dev/led/error
 173 .Ed
 174 .Sh SEE ALSO
 175 .Xr morse 6
 176 .Sh HISTORY
 177 The
 178 .Nm
 179 driver first appeared in
 180 .Fx 5.2 .
 181 .Sh AUTHORS
 182 .An -nosplit
 183 This software was written by
 184 .An Poul-Henning Kamp
 185 .Aq phk@FreeBSD.org .
 186 .Pp
 187 This manual page was written by
 188 .An Sergey A. Osokin
 189 .Aq osa@FreeBSD.org
 190 and
 191 .An Poul-Henning Kamp
 192 .Aq phk@FreeBSD.org .