share/man/man4/ds3231.4

   1 .\"
   2 .\" Copyright (c) 2014 Luiz Otavio O Souza <loos@freebsd.org>
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\"
  14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  15 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  16 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  17 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  18 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  19 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  20 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  21 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  22 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  23 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD$
  26 .\"
  27 .Dd February 12, 2016
  28 .Dt DS3231 4
  29 .Os
  30 .Sh NAME
  31 .Nm ds3231
  32 .Nd Extremely Accurate i2c-integrated RTC/TCXO/Crystal
  33 .Sh SYNOPSIS
  34 .Cd "device iic"
  35 .Cd "device iicbus"
  36 .Cd "device ds3231"
  37 .Sh DESCRIPTION
  38 The
  39 .Nm
  40 is a low-cost, extremely accurate I2C realtime clock (RTC) with an
  41 integrated temperature-compensated crystal oscillator (TCXO) and crystal.
  42 .Pp
  43 The device incorporates a battery input and maintains accurate timekeeping
  44 when main power to the device is interrupted.
  45 .Pp
  46 Access to
  47 .Nm
  48 data is made with the
  49 .Xr sysctl 8
  50 interface:
  51 .Bd -literal
  52 dev.ds3231.0.%desc: Maxim DS3231 RTC
  53 dev.ds3231.0.%driver: ds3231
  54 dev.ds3231.0.%location: addr=0xd0
  55 dev.ds3231.0.%pnpinfo: name=rtc compat=maxim,ds3231
  56 dev.ds3231.0.%parent: iicbus1
  57 dev.ds3231.0.temperature: 23.2C
  58 dev.ds3231.0.temp_conv: 0
  59 dev.ds3231.0.bbsqw: 0
  60 dev.ds3231.0.sqw_freq: 8192
  61 dev.ds3231.0.sqw_mode: interrupt
  62 dev.ds3231.0.32khz_enable: 1
  63 .Ed
  64 .Bl -tag -width ".Va dev.ds3231.%d.temperature"
  65 .It Va dev.ds3231.%d.temperature
  66 The read-only value of the current temperature read by the RTC.
  67 .It Va dev.ds3231.%d.temp_conv
  68 Start a new temperature conversion.
  69 When read as 1, a temperature conversion is in progress.
  70 When read as 0 and then set to 1, a temperature conversion is started.
  71 The temperature conversion runs automatically on power up and once every 64
  72 seconds afterward.
  73 .It Va dev.ds3231.%d.bbsqw
  74 If set to 1 and
  75 .Va dev.ds3231.%d.sqw_mode
  76 is set to square-wave, battery-backed square-wave output is enabled.
  77 If set to 0, the SQW pin will be set to high impendance when the RTC is
  78 being powered by battery.
  79 .It Va dev.ds3231.%d.sqw_freq
  80 Select the frequency of the SQW pin when the square-wave output is enabled on
  81 .Va dev.ds3231.%d.sqw_mode .
  82 It can be set to 1, 1024, 4096, and 8192.
  83 .It Va dev.ds3231.%d.sqw_mode
  84 Set the operation mode for the SQW pin.
  85 It can be set to 'interrupt' (default) or 'square-wave'.
  86 In interrupt mode, the SQW pin is used to generate interrupts for the RTC
  87 alarms.
  88 In square-wave mode, the SQW pin drives a square-wave of
  89 .Va dev.ds3231.%d.sqw_freq
  90 frequency.
  91 .It Va dev.ds3231.%d.32khz_enable
  92 Enable the 32kHz output.
  93 .El
  94 .Pp
  95 Please check the
  96 .Nm
  97 datasheet for more details.
  98 .Pp
  99 On a
 100 .Xr device.hints 5
 101 based system, such as
 102 .Li MIPS ,
 103 these values are configurable for
 104 .Nm :
 105 .Bl -tag -width ".Va hint.ds3231.%d.addr"
 106 .It Va hint.ds3231.%d.at
 107 The
 108 .Xr iicbus 4
 109 that the
 110 .Nm
 111 is connected to.
 112 .It Va hint.ds3231.%d.addr
 113 The 8-bit i2c address of
 114 .Nm .
 115 The default 8-bit address for
 116 .Nm
 117 is 0xd0.
 118 .El
 119 .Pp
 120 On a
 121 .Xr FDT 4
 122 based system the following properties must be set:
 123 .Bl -tag -width ".Va compatible"
 124 .It Va compatible
 125 Must always be set to "maxim,ds3231".
 126 .It Va reg
 127 The 7-bit i2c address of
 128 .Nm .
 129 The default 7-bit address for
 130 .Nm
 131 is 0x68.
 132 .El
 133 .Sh SEE ALSO
 134 .Xr fdt 4 ,
 135 .Xr iic 4 ,
 136 .Xr iicbus 4 ,
 137 .Xr sysctl 8
 138 .Sh HISTORY
 139 The
 140 .Nm
 141 driver first appeared in
 142 .Fx 11.0 .
 143 .Sh AUTHORS
 144 .An -nosplit
 145 The
 146 .Nm
 147 driver and this manual page were written by
 148 .An Luiz Otavio O Souza Aq Mt loos@FreeBSD.org .