'\"
'\" Copyright (c) 2018 Alastair D'Silva
'\" (alastair@d-silva.org)
'\"
'\" Device manual page for the OWFS -- 1-wire filesystem package.
'\" InfernoEmbedded Softdevices
'\"
'\" Free for all use. No warranty. None. Use at your own risk.
'\"
.TH InfernoEmbedded 3  2018 "OWFS Manpage" "One-Wire File System"
.SH NAME
.TP
.B InfernoEmbedded
\- InfernoEmbedded Softdevices: RGBW Controllers, Switch Masters, Firmware Updater
.SH SYNOPSIS
Software-implemented devices based on https://github.com/InfernoEmbedded/onewire-softdevice
.PP
.B ED
[.]XXXXXXXXXXXX[XX][/[
.B device
|
.B version
|
.B status
|
.B enter_firmware_update
|
'\"
'\" Copyright (c) 2003-2004 Paul H Alfille, MD
'\" (paul.alfille@gmail.com)
'\"
'\" Program manual page for the OWFS -- 1-wire filesystem package
'\" Based on Dallas Semiconductor, Inc's datasheets, and trial and error.
'\"
'\" Free for all use. No warranty. None. Use at your own risk.
'\"
.B address
|
.B crc8
|
.B id
|
.B locator
|
.B r_address
|
.B r_id
|
.B r_locator
|
.B type
]]
.SH FAMILY CODE
.PP
.I ED
.SH GENERIC PROPERTIES
These properties are applicable to all Inferno Embedded softdevices.
.SS device
.I read-only, ascii text
.br
The type of InfernoEmbedded Softdevice detected.
.SS version
.I read-only, integer
.br
The version number reported by the device.
.SS status
.I read-only, integer
.br
The 64 bit status register of the device.
.SS enter_firmware_update
.I write-only, yes-no
.br
Write anything to reboot the device into the bootloader for firmware update. This may also be forced if you have physical access to the device by shorting SWCLK to ground on the device's programming header when powering up the device.

.SH FIRMWARE UPDATER PROPERTIES
These properties are available when the device has entered firmware update mode.

.SS firmware_bootloader_size
.I read-only, integer
.br
The reserved size for the bootloader.
.SS firmware_range
.I read-only, ascii text
.br
The range of addresses available for the application (0xNNNN-0xNNNN).
.SS erase_firmware
.I write-only, yes-no
.br
Write anything to erase the current application and prepare the device to accept a new firmware.
.SS update_firmware
.I write-only, binary data
.br
Write the binary data for a firmware update here to reprogram the device after erasing.
.SS exit_firmware_update
.I write-only, yes-no
.br
Write anything to exit firmware update and start the application.

.SH RGBW CONTROLLER PROPERTIES
These controllers control a number of channels of RGBW lights.
.SS rgbw_all_off
.I write-only, yes-no
.br
Write anything to turn off all channels
.SS rgbw_channels
.I read-only, integer
.br
The number of RGBW channels supported by this device.
.SS rgbw_channelNN
.I read-write, ascii text
.br
Set the current value of channel NN, as:
RRR,GGG,BBB,WWW,nnn  where:
  RRR,GGG,BBB,WWW is the red, green, blue values respectively (0-255)
  nnn is the time to fade from the current colour to the new one, in milliseconds (0-16M). On read, this is time remaining for the current fade to complete.

.SH SWITCH MASTERS
These devices have a number of indicator LEDs, switch inputs and relay outputs. Each are grouped into ports of a certain number of channels.

.SS switch_ports
.I read-only, integer
.br
The number of switch ports available.
.SS switch_channels
.I read-only, integer
.br
The number of channels available per switch port.
.SS switch_refresh_activations
.I write-only, yes-no
.br
Write anything here to update the values of all switch ports from the device.
.SS switch_portN
.I read-only, ascii text
.br
The last fetched state for the port (use switch_refresh_activations to fetch the state). Formatted as "channel0,channel1...channelN", where each channel is '0' or '1' depending on whether it is activated.
.SS set_switch_type
.I write-only, ascii text
.br
Sets the type of switch connected to the device. Format "port,channel,type" where port and channel are integer IDs, and type is:
.br
  0 Toggle switch to VCC with pull-downs enabled on the device
  1 Toggle switch to Gnd with pull-ups enabled on the device
  2 Momentary switch to VCC with pull-downs enabled on the device
  3 Momentary switch to Gnd with pull-ups enabled on the device
.SS led_ports
.I read-only, integer
.br
The number of LED ports available.
.SS led_channels
.I read-only, integer
.br
The number of channels available per LED port.
.SS led_portN
.I read-write, ascii text
.br
The state for the port. Formatted as "channel0,channel1...channelN", where each channel is '0' or '1' depending on whether the LED is lit.
.SS relay_ports
.I read-only, integer
.br
The number of relay ports available.
.SS relay_channels
.I read-only, integer
.br
The number of channels available per relay port.
.SS relay_portN
.I read-write, ascii text
.br
The state for the port. Formatted as "channel0,channel1...channelN", where each channel is '0' or '1' depending on whether the relay is activated.
.SS relay_modeN
.I read-write, ascii text
.br
The mode for each relay on the port. Formatted as "channel0,channel1...channelN", where each channel is one of the following modes:
.br
  0 Channel operates independently
  1 Channel operates as a member of an even/odd pair
.br
If the channels are operated as pairs, the even numbered relay is activated when the even numbered channel is turned on, and the odd numbered relay is activated when the even numbered channel is turned off. The odd numbered channel has no effect. This is useful when controlling devices such as roller shutters, projector screens and air conditioning dampers, which require one relay to be activated to open, and another to close.
.SS relay_timeoutN
.I read-write, ascii text
.br
The timeout for each relay on the port. Formatted as "channel0,channel1...channelN", where each channel is an integer (0-255) representing the number of seconds the relay will remain activated when operating as an even/odd pair. 

.SH ADDRESSING
'\"
'\" Copyright (c) 2003-2004 Paul H Alfille, MD
'\" (paul.alfille@gmail.com)
'\"
'\" Program manual page for the OWFS -- 1-wire filesystem package
'\" Based on Dallas Semiconductor, Inc's datasheets, and trial and error.
'\"
'\" Free for all use. No warranty. None. Use at your own risk.
'\"
All 1-wire devices are factory assigned a unique 64-bit address. This address is of the form:
.TP
.B Family Code
8 bits
.TP
.B Address
48 bits
.TP
.B CRC
8 bits
.IP
.PP
Addressing under OWFS is in hexadecimal, of form:
.IP
.B 01.123456789ABC
.PP
where
.B 01
is an example 8-bit family code, and
.B 12345678ABC
is an example 48 bit address.
.PP
The dot is optional, and the CRC code can included. If included, it must be correct.
.SH SEE ALSO
.SS Programs
.B owfs (1) owhttpd (1) owftpd (1) owserver (1)
.B owdir (1) owread (1) owwrite (1) owpresent (1)
.B owtap (1)
.SS Configuration and testing
.B owfs (5) owtap (1) owmon (1)
.SS Language bindings
.B owtcl (3) owperl (3) owcapi (3)
.SS Clocks
.B DS1427 (3) DS1904 (3) DS1994 (3) DS2404 (3) DS2404S (3) DS2415 (3) DS2417 (3)
.SS ID
.B DS2401 (3) DS2411 (3) DS1990A (3)
.SS Memory
.B DS1982 (3) DS1985 (3) DS1986 (3) DS1991 (3) DS1992 (3) DS1993 (3) DS1995 (3) DS1996 (3) DS2430A (3) DS2431 (3) DS2433 (3) DS2502 (3) DS2506 (3) DS28E04 (3) DS28EC20 (3)
.SS Switches
.B DS2405 (3) DS2406 (3) DS2408 (3) DS2409 (3) DS2413 (3) DS28EA00 (3) InfernoEmbedded (3)
.SS Temperature
.B DS1822 (3) DS1825 (3) DS1820 (3) DS18B20 (3) DS18S20 (3) DS1920 (3) DS1921 (3) DS1821 (3) DS28EA00 (3) DS28E04 (3) EDS0064 (3) EDS0065 (3) EDS0066 (3) EDS0067 (3) EDS0068 (3) EDS0071 (3) EDS0072 (3) MAX31826 (3)
.SS Humidity
.B DS1922 (3) DS2438 (3) EDS0065 (3) EDS0068 (3)
.SS Voltage
.B DS2450 (3)
.SS Resistance
.B DS2890 (3)
.SS Multifunction (current, voltage, temperature)
.B DS2436 (3) DS2437 (3) DS2438 (3) DS2751 (3) DS2755 (3) DS2756 (3) DS2760 (3) DS2770 (3) DS2780 (3) DS2781 (3) DS2788 (3) DS2784 (3)
.SS Counter
.B DS2423 (3)
.SS LCD Screen
.B LCD (3) DS2408 (3)
.SS Crypto
.B DS1977 (3)
.SS Pressure
.B DS2406 (3) TAI8570 (3) EDS0066 (3) EDS0068 (3)
.SS Moisture
.B EEEF (3) DS2438 (3)
.SH AVAILABILITY
https://github.com/InfernoEmbedded/onewire-softdevice
.SH AUTHOR
Alastair D'Silva (alastair@d-silva.org)