Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
OWFTPD(1)		     One-Wire File System		     OWFTPD(1)

NAME
       owftpd -	Anoymous FTP server for	1-wire access

SYNOPSIS
       owftpd [	-c config ] -d serialport | -u | -s [host:]port	[ -p host:tcp-
       port ]

DESCRIPTION
   1-Wire
       1-wire is a wiring protocol and series of devices designed and manufac-
       tured  by  Dallas  Semiconductor, Inc. The bus is a low-power low-speed
       low-connector scheme where the data line	can also provide power.

       Each device is uniquely and unalterably	numbered  during  manufacture.
       There  are a wide variety of devices, including memory, sensors (humid-
       ity, temperature, voltage, contact, current), switches, timers and data
       loggers.	 More complex devices (like thermocouple sensors) can be built
       with these basic	devices. There are also	1-wire devices that  have  en-
       cryption	included.

       The  1-wire  scheme uses	a single bus master and	multiple slaves	on the
       same wire. The bus master initiates all communication. The  slaves  can
       be individually discovered and addressed	using their unique ID.

       Bus  masters come in a variety of configurations	including serial, par-
       allel, i2c, network or USB adapters.

   OWFS	design
       OWFS is a suite of programs that	designed to make the  1-wire  bus  and
       its  devices easily accessible. The underlying principle	is to create a
       virtual filesystem, with	the unique ID being the	directory, and the in-
       dividual	 properties of the device are represented as simple files that
       can be read and written.

       Details of the individual slave or master design	are  hidden  behind  a
       consistent interface. The goal is to provide an easy set	of tools for a
       software	designer to create monitoring or control  applications.	 There
       are some	performance enhancements in the	implementation,	including data
       caching,	parallel access	to bus masters,	and aggregation	of device com-
       munication.  Still the fundamental goal has been	ease of	use, flexibil-
       ity and correctness rather than speed.

   owftpd
       owhttpd (1) is an anonymous ftp	(file-transfer-protocol)  server  that
       shows  the Dallas/Maxim 1-Wire bus attached to a	computer. The main di-
       rectory shows the devices found,	You can	then  navigate	to  individual
       devices,	view and set their properties.

       owftpd (1) uses the same	naming convention as owfs (1) and owhppt (1) ,
       where the URL corresponds to the	filename.

       The ftp server is a modified version of oftpd by	Shane Kerr. It	serves
       no  files  from the disk, only virtual files from the 1-wire bus. Secu-
       rity should therefore be	good. Only the 1-wire bus is at	risk.

Device Options (1-wire Bus Master)
       These options specify the device	(bus master) connecting	 the  computer
       to  the	1-wire bus. The	1-wire slaves are connected to the 1-wire bus,
       and the bus master connects to a	port on	the computer and controls  the
       1-wire  bus.  The  bus  master is either	an actual physical device, the
       kernel w1 module, or an owserver	(1).

       At least	one device option is required. There is	no default. More  than
       one device can be listed, and all will be used. (A logical union	unless
       you explore the /bus.n/ directories.)

       Linux and BSD enforce a security	policy restricting access to  hardware
       ports.  You must	have sufficient	rights to access the given port	or ac-
       cess will silently fail.

* Serial devices
       port specifies a	serial port, e.g.  /dev/ttyS0 or an USB	port  accessed
       as serial port, e.g. /dev/ttyUSB0

       If  OWFS	 was  built  with  libftdi support, you	may be able to use the
       ftdi: prefix in any of the options as port to address a FTDI-based  USB
       device.
       For details, see	the FTDI ADDRESSING section.

       -d port | --device=port (DS2480B)
	      DS2480B-based  bus master	(like the DS9097U or an	adapter	of the
	      LINK family in emulation mode). If the adapter doesn't  respond,
	      a	 passive  type (DS9907E	or diode/resistor) circuit will	be as-
	      sumed.

       --serial_flextime | --serial_regulartime	(DS2480B)
	      Changes details of bus timing (see DS2480B datasheet). Some  de-
	      vices, like the Swart LCD	cannot work with flextime.

       --baud=1200|9600|19200|38400|57600|115200 (DS2480B,LINK,HA5)
	      Sets  the	 initial  serial  port communication speed for all bus
	      masters. Not all serial devices  support	all  speeds.  You  can
	      change  the individual bus master	speed for a device of the LINK
	      family and DS2880B in the	interface/settings directory. The  HA5
	      speed  is	 set in	hardware, so the command line baud rate	should
	      match that rate.
	      Usually the default settings (9600 for a device of the LINK fam-
	      ily  and DS2480B ) and 115200 for	the HA5	are sane and shouldn't
	      be changed.

       --straight_polarity  | --reverse_polarity (DS2480B)
	      Reverse polarity of the DS2480B output transistors?  Not	needed
	      for the DS9097U, but required for	some other designs.

       --link=port (LINK)
	      iButtonLink  LINK	 adapter (all versions)	in non-emulation mode.
	      Uses an ascii protocol over serial.
	      This supports the	 simplified  ftdi:<serial  number>  addressing
	      scheme.

       --ha7e=port (HA7E)
	      Embedded	Data Systems HA7E adapter ( and	HA7S ) in native ascii
	      mode.

       --ha5=port | --ha5=port:a | --ha5=port:acg (HA5)
	      Embedded Data Systems HA5	mutidrop adapter in native ascii mode.
	      Up to 26 adapters	can share the same port, each with an assigned
	      letter. If no letter specified, the program will	scan  for  the
	      first response (which may	be slow).

       --checksum | --no_checksum (HA5)
	      Turn  on (default) or off	the checksum feature of	the HA5	commu-
	      nication.

       --passive=port |	--ha2=port | --ha3=port	| --ha4b=port (Passive)
	      Passive 1-wire adapters. Powered off the serial port  and	 using
	      passive electrical components (resitors and diodes).

       --8bit |	--6bit (Passive)
	      Synthesize  the  1-wire waveforme	using a	6-bit (default)	serial
	      word, or 8-bit word. Not all UART	devices	support	6  bit	opera-
	      tion.

       --timeout_serial=5
	      Timeout (in seconds) for all serial communications. 5 second de-
	      fault. Can be altered dynamically	under /settings/timeout/serial

* USB devices
       The only	supported true USB bus masters are based on the	 DS2490	 chip.
       The  most  common  is the DS9490R which has an included 1-wire ID slave
       with family code	81.

       There are also bus masters based	on the serial chip with	a USB  to  se-
       rial  conversion	built in. These	are supported by the serial bus	master
       protocol.

       -u | --usb
	      DS2490 based bus master (like the	DS9490R).

       -u2 | --usb=2
	      Use the second USB bus master.  (The  order  isn't  predicatble,
	      however,	since the operating system does	not consistently order
	      USB devices).

       -uall | --usb=ALL
	      Use all the USB devices.

       --usb_flextime |	--usb_regulartime
	      Changes the details of 1-wire waveform timing for	 certain  net-
	      work configurations.

       --altusb
	      Willy Robion's alternative USB timing.

       --timeout_usb=5
	      Timeout  for USB communications. This has	a 5 second default and
	      can be changed dynamically under /settings/timeout/usb

* I2C devices
       I2C is  2 wire protocol used for	chip-to-chip  communication.  The  bus
       masters:	 DS2482-100,  DS2482-101  and  DS2482-800 can specify (via pin
       voltages) a subset of addresses on the i2c bus. Those choices are

       i2c_address

       0,1,2,3
	      0x18,0x19,0x1A,0x1B

       4,5,6,7
	      0x1C,0x1D,0x1E,0x1F (DS2482-800 only)

       port for	i2c masters have the form /dev/i2c-0, /dev/i2c-1, ...

       -d port | --device=port
	      This simple form only permits a  specific	 port  and  the	 first
	      available	i2c_address

       --i2c=port | --i2c=port:i2c_address | --i2c=port:ALL
	      Specific	i2c port and the i2c_address is	either the first, spe-
	      cific, or	all or them. The i2c_address is	0,1,2,...

       --i2c | --i2c=: | --i2c=ALL:ALL
	      Search the available i2c buses for either	the first, the	first,
	      or every i2c adapter.

       The DS2482-800 masters 8	1-wire buses and so will generate 8 /bus.n en-
       tries.

* Network devices
       These bus masters communicate via the tcp/ip network  protocol  and  so
       can  be located anywhere	on the network.	 The network_address is	of the
       form tcp_address:port

       E.g. 192.168.0.1:3000 or	localhost:3000

       --link=network_address
	      LinkHubE network LINK adapter by iButtonLink

       --ha7net=network_address	| --ha7net
	      HA7Net network 1-wire adapter with specified tcp address or dis-
	      covered by udp multicast.	By Embedded Data Systems
	      --timeout_ha7=60	specific timeout for HA7Net communications (60
	      second default).

       --etherweather=network_address
	      Etherweather adapter

       -s network_address | --server=network_address
	      Location of an owserver (1) program that	talks  to  the	1-wire
	      bus. The default port is 4304.

       --timeout_network=5
	      Timeout for network bus master communications. This has a	1 sec-
	      ond default and can be changed dynamically under /settings/time-
	      out/network

* Simulated devices
       Used  for testing and development. No actual hardware is	needed.	Useful
       for separating the hardware development from the	rest of	 the  software
       design.

       devices
	      is  a  list  of  comma-separated 1-wire devices in the following
	      formats. Note that a valid CRC8 code is created automatically.

       10,05,21
	      Hexadecimal family codes (the DS18S20, DS2405 and	DS1921 in this
	      example).

       10.12AB23431211
	      A	 more  complete	hexadecimal unique address. Useful when	an ac-
	      tual hardware device should be simulated.

       DS2408,DS2489
	      The 1-wire device	name. (Full ID cannot  be  speciifed  in  this
	      format).

       --fake=devices
	      Random address and random	values for each	read. The device ID is
	      also random (unless specified).

       --temperature_low=12 --temperature_high=44
	      Specify the temperature limits for the fake adapter  simulation.
	      These  should be in the same temperature scale that is specified
	      in the command line. It is possible to change the	limits dynami-
	      cally  for  each	adapter	 under /bus.x/interface/settings/simu-
	      lated/[temperature_low|temperature_high]

       --tester=devices
	      Predictable address and predictable values for each  read.  (See
	      the website for the algorhythm).

* w1 kernel module
       This a linux-specific option for	using the operating system's access to
       bus masters. Root access	is required and	the implementation  was	 still
       in progress as of owfs v2.7p12 and linux	2.6.30.

       Bus masters are recognized and added dynamically. Details of the	physi-
       cal bus master are not accessible, bu they include USB, i2c and a  num-
       ber of GPIO designs on embedded boards.

       Access  is  restrict to superuser due to	the netlink broadcast protocol
       employed	by w1. Multitasking must be configured (threads) on the	compi-
       lation.

       --w1   Use the linux kernel w1 virtual bus master.

       --timeout_w1=10
	      Timeout  for w1 netlink communications. This has a 10 second de-
	      fault and	can be changed dynamically under /settings/timeout/w1

FTDI ADDRESSING
       FTDI is a brand of USB-to-serial	chips which are	very common.  If  your
       serial  device  is  connected  via  a USB serial	dongle based on	a FTDI
       chip, or	if your	adapter	uses a built-in	FTDI USB  chip	(for  example,
       the LinkUSB), you can use this FTDI addressing.

       The  main  benefit with this mode of access is that we can decrease the
       communication delay, yielding twice as  fast  1-Wire  communication  in
       many cases.

       The  following  values for port can be used to identify a specific FTDI
       port in several of the serial devices options.
       Note that this requires that OWFS is built with libftdi support,	 which
       might not be the	case in	standard repositories.

       ftdi:d:<device-node>
	      path  of	bus and	device-node (e.g. "003/001") within usb	device
	      tree (usually at /proc/bus/usb/ or /dev/bus/usb/)

       ftdi:i:<vendor>:<product>
	      first device with	given vendor and product id, ids can be	 deci-
	      mal, octal (preceded by "0") or hex (preceded by "0x")

       ftdi:i:<vendor>:<product>:<index>
	      as  above	 with  index  being the	number of the device (starting
	      with 0) if there are more	than one

       ftdi:s:<vendor>:<product>:<serial number>
	      the device with given vendor id, product id  and	serial	number
	      string

       The above formats are parsed fully by libftdi (minus the	ftdi: prefix).

   Simplified device serial-only support
       An  additional  format  is  supported, for certain bus types. This only
       specifies the USB serial	number.

       ftdi:<serial number>
	      Identifies a FTDI	device by serial number	only.  Currently, this
	      is  only	valid  for  the	 VID/PID  found	 on  the LinkUSB (i.e.
	      --link).	Note that those	VID/PID's  are	the  default  for  any
	      FT232R device, and in no way exclusive to	LinkUSB.

   Permsissions
       In  order  to run owserver (1) without root privileges -	as you should,
       you must	have sufficient	permissions to the raw USB node	 your  adapter
       is   connected	to   e.g.  "003/001"  (usually	at  /proc/bus/usb/  or
       /dev/bus/usb/).

       An easy way to achieve this would be using chown	(1):

       sudo chown :<your user> /dev/bus/usb/003/001
	      changes the group	of the raw USB	node  "003/001"	 from  default
	      "root" to	"<your user>"

       You can also write a udev (1) rule for your adapter:

       SUBSYSTEM=="usb",  DRIVER=="usb",  ATTR{idVendor}=="0403", ATTR{idProd-
       uct}=="6001", ATTR{serial}=="AK0048A0", GROUP="owsrv"
	      saved   as    a	 file	 e.g.	 "10-FTDI-LinkUSB.rules"    in
	      "/etc/udev/rules.d/",  this  rule	 will  automate	the process of
	      changing the group to "owsrv" of the raw USB  node  the  LinkUSB
	      adapter with S/N:AK0048A0	is connected to.

   Serial USB node
       Communication in	FTDI mode accesses the RAW USB node and	NOT the	serial
       USB node	your OS	might have created automatically e.g. /dev/ttyUSB0.
       As a side effect, if existing, the serial USB node e.g. /dev/ttyUSB0 is
       removed	on successful starting of owserver (1).	After it's termination
       un- and re-plugging the adapter,	or un- and  reloading  of  the	module
       ftdi_sio	will recreate the serial USB node.

   Finding FTDI	related	information on your USB	adapter
       owusbprobe  is  THE tool	to find	the information	needed for direct FTDI
       addressing
       However this tool might not yet be packaged in your  version.  Alterna-
       tively you can also use lsusb to	find the usb node your adapter is con-
       nected to, and then use lsusb again on this very	node:

       sudo lsusb -D /path/to/your/raw/USB/device/node	 |egrep	 "idVendor|id-
       Product|iSerial"
	      sudo is necessary	to get the value of iSerial field, if the per-
	      missions are still unchanged

   Examples FTDI addressing
       owserver	-d ftdi:s:0x0403:0x6001:A800bXHr
	      starts	     owserver	      with	    a	       LinkUSB
	      (VID:0x0403,PID:0x6001,S/N:A800bXHr)  as	bus master in DS2480B-
	      based emulation mode with	direct FTDI access

       owserver	--link=ftdi:A800bXHr
	      starts owserver with a  LinkUSB  (S/N:A800bXHr)  as  bus	master
	      identified by serial number only in native mode with direct FTDI
	      access

SPECIFIC OPTIONS
   -p host:portnum
       (Optional) Sets the tcp port the	ftp server runs	on.  Access  with  the
       URL ftp://anonymous@servernameoripaddress:portnum

       The  well  known	ftp port, 21, will be used by default. Since this port
       number is in the	restricted range, special permission  is  usually  re-
       quired.

TEMPERATURE SCALE OPTIONS
   -C --Celsius
   -F --Fahrenheit
   -K --Kelvin
   -R --Rankine
       Temperature scale used for data output. Celsius is the default.

       Can  also  be  changed  within  the program at /settings/units/tempera-
       ture_scale

PRESSURE SCALE OPTIONS
   --mbar (default)
   --atm
   --mmHg
   --inHg
   --psi
   --Pa
       Pressure	scale used for data output. Millibar is	the default.

       Can  also  be  changed  within  the  program  at	 /settings/units/pres-
       sure_scale

FORMAT OPTIONS
       Choose  the  representation of the 1-wire unique	identifiers. OWFS uses
       these identifiers as unique directory names.

       Although	several	display	formats	are selectable,	all must be in family-
       id-crc8 form, unlike some other programs	and the	labelling on iButtons,
       which are crc8-id-family	form.

   -f --format="f[.]i[[.]c]"
       Display format for the 1-wire devices. Each device has a	8byte address,
       consisting of:

       f      family code, 1 byte

       i      ID number, 6 bytes

       c      CRC checksum, 1 byte

       Possible	 formats are f.i (default, 01.A1B2C3D4E5F6), fi	fic f.ic f.i.c
       and fi.c

       All formats are accepted	as input, but the output will be in the	speci-
       fied format.

       The  address  elements  can be retrieved	from a device entry in owfs by
       the family, id and crc8 properties, and as a whole with	address.   The
       reversed	id and address can be retrieved	as r_id	and r_address.

JOB CONTROL OPTIONS
   -r --readonly
   -w --write
       Do  we  allow  writing  to  the	1-wire	bus  (writing  memory, setting
       switches, limits, PIOs)?	The write option is  available	for  symmetry,
       it's the	default.

   -P --pid-file filename
       Places  the PID -- process ID of	owfs into the specified	filename. Use-
       ful for startup scripts control.

   --background	| --foreground
       Whether the program releases the	console	and runs in the	background af-
       ter evaluating command line options.  background	is the default.

   --error_print=0|1|2|3
       =0     default mixed destination: stderr	foreground / syslog background

       =1     syslog only

       =2     stderr only

       =3     /dev/null	(quiet mode).

   --error_level=0..9
       =0     default errors only

       =1     connections/disconnections

       =2     all high level calls

       =3     data summary for each call

       =4     details level

       _4     debugging	chaff

       --error_level=9 produces	a lot of output

CONFIGURATION FILE
   -c file | --configuration file
       Name  of	 an owfs (5) configuration file	with more command line parame-
       ters

HELP OPTIONS
       See also	this man page and the web site http://www.owfs.org

   -h --help=[device|cache|program|job|temperature]
       Shows basic summary of options.

       device 1-wire bus master	options

       cache  cache and	communication size and timing

       program
	      mountpoint or TCP	server settings

       job    control and debugging options

       temperature
	      Unique ID	display	format and temperature scale

   -V --version
       Version of this program and related libraries.

TIME OPTIONS
       Timeouts	for the	bus masters were previously listed in Device  options.
       Timeouts	 for  the cache	affect the time	that data stays	in memory. De-
       fault values are	shown.

   --timeout_volatile=15
       Seconds until a volatile	property expires in the	cache. Volatile	 prop-
       erties are those	(like temperature) that	change on their	own.

       Can be changed dynamically at /settings/timeout/volatile

   --timeout_stable=300
       Seconds until a stable property expires in the cache. Stable properties
       are those that shouldn't	change unless explicitly changed. Memory  con-
       tents for example.

       Can be changed dynamically at /settings/timeout/stable

   --timeout_directory=60
       Seconds until a directory listing expires in the	cache. Directory lists
       are the 1-wire devices found on the bus.

       Can be changed dynamically at /settings/timeout/directory

   --timeout_presence=120
       Seconds until the presence and bus location of a	1-wire device  expires
       in the cache.

       Can be changed dynamically at /settings/timeout/presence

       There are also timeouts for specific program responses:

   --timeout_server=5
       Seconds	until  the  expected  response from the	owserver (1) is	deemed
       tardy.

       Can be changed dynamically at /settings/timeout/server

   --timeout_ftp=900
       Seconds that an ftp session is kept alive.

       Can be changed dynamically at /settings/timeout/ftp

EXAMPLE
       owftpd -d /dev/ttyS0
	      Ftp server runs on default tcp port 21, serial adapter at	ttyS0

       owftpd -s littlehost:4304 --error_level=3
	      Ftp server on default port 21, from owserver (1) process on host
	      "littlehost", extensive error messages.

AVAILABILITY
       http://www.owfs.org

SEE ALSO
   Programs
       owfs  (1)  owhttpd  (1)	owftpd	(1)  owserver (1) owdir	(1) owread (1)
       owwrite (1) owpresent (1) owtap (1)

   Configuration and testing
       owfs (5)	owtap (1) owmon	(1)

   Language bindings
       owtcl (3) owperl	(3) owcapi (3)

   Clocks
       DS1427 (3) DS1904(3) DS1994 (3)	DS2404	(3)  DS2404S  (3)  DS2415  (3)
       DS2417 (3)

   ID
       DS2401 (3) DS2411 (3) DS1990A (3)

   Memory
       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)

   Switches
       DS2405 (3) DS2406 (3) DS2408 (3)	DS2409 (3) DS2413 (3) DS28EA00 (3)

   Temperature
       DS1822  (3)  DS1825  (3)	 DS1820	(3) DS18B20 (3)	DS18S20	(3) DS1920 (3)
       DS1921 (3) DS1821 (3) DS28EA00 (3) DS28E04 (3)

   Humidity
       DS1922 (3)

   Voltage
       DS2450 (3)

   Resistance
       DS2890 (3)

   Multifunction (current, voltage, temperature)
       DS2436 (3) DS2437 (3) DS2438 (3)	 DS2751	 (3)  DS2755  (3)  DS2756  (3)
       DS2760 (3) DS2770 (3) DS2780 (3)	DS2781 (3) DS2788 (3) DS2784 (3)

   Counter
       DS2423 (3)

   LCD Screen
       LCD (3) DS2408 (3)

   Crypto
       DS1977 (3)

   Pressure
       DS2406 (3) -- TAI8570

AUTHOR
       Paul Alfille (paul.alfille@gmail.com)

OWFS Manpage			     2004			     OWFTPD(1)

NAME | SYNOPSIS | DESCRIPTION | Device Options (1-wire Bus Master) | * Serial devices | * USB devices | * I2C devices | * Network devices | * Simulated devices | * w1 kernel module | FTDI ADDRESSING | SPECIFIC OPTIONS | TEMPERATURE SCALE OPTIONS | PRESSURE SCALE OPTIONS | FORMAT OPTIONS | JOB CONTROL OPTIONS | CONFIGURATION FILE | HELP OPTIONS | TIME OPTIONS | EXAMPLE | AVAILABILITY | SEE ALSO | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=owftpd&sektion=1&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help