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