OWFTPD(1)

📦
version 3.2p4 · 2 versions
, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

okay so bestie 💖 welcome to the owftpd page — that's OWFTPD(1), the One-Wire File System's anonymous FTP server, and yes it's a whole saga. Grab a snack, we're doing this in parts. 🍓

🎀 NAME 🎀

owftpd — Anoymous FTP server for 1-wire access

not me leaving the typo exactly as written because it's in the source, it's canon, it's heritage 💅

🌈 SYNOPSIS 🌈

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

✨ DESCRIPTION ✨

🦋 1-Wire 🦋

So, 1-wire is a wiring protocol and a whole family of devices, designed and manufactured by Dallas Semiconductor, Inc. 🏭 The bus itself is low-power, low-speed, and low-connector — and the slay of it is that the data line also provides power. One wire doing two jobs? main character energy fr. 👑

Every single device gets uniquely and unalterably numbered during manufacture. You do not get to change it. It's her number, it's forever. 💖

The device lineup is wide: memory, sensors (humidity, temperature, voltage, contact, current), switches, timers, and data loggers. And if that's not enough, you can build more complex devices — like thermocouple sensors — out of these basic ones. There are also 1-wire devices with encryption baked in 🔐.

The scheme is one bus master and multiple slaves on the same wire. The bus master initiates all communication — no side conversations. The slaves get individually discovered and addressed using their unique ID. 🫶

Bus masters come in a bunch of different configurations, including serial, parallel, i2c, network or USB adapters.

🌸 OWFS design 🌸

OWFS is a suite of programs designed to make the 1-wire bus and its devices easily accessible. The underlying principle: build a virtual filesystem, where the unique ID is the directory, and each individual property of the device is a simple file you can read and write. 📂✨

All the messy details of the individual slave or master design stay hidden behind a consistent interface. The goal is to hand a software designer an easy set of tools for building monitoring or control applications. There are performance enhancements in the implementation too — data caching, parallel access to bus masters, and aggregation of device communication. But the fundamental goal has always been ease of use, flexibility 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 directory shows the devices found, and 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. So security 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) that connects your computer to the 1-wire bus. The 1-wire slaves hang off the 1-wire bus, and the bus master plugs into 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 of them will be used. (It's a logical union, unless you go exploring 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 access will silently fail. 💀 No error, no nothing, it just won't work. You've been warned.

⭐ Serial devices ⭐

port specifies a serial port, e.g. /dev/ttyS0, or a USB port accessed as a 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 <small>(DS2480B)</small> — 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 assumed.
  • --serial_flextime | --serial_regulartime <small>(DS2480B)</small> — Changes details of bus timing (see DS2480B datasheet). Some devices, like the Swart LCD, cannot work with flextime.
  • --baud=1200|9600|19200|38400|57600|115200 <small>(DS2480B, LINK, HA5)</small> — 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 family and DS2480B) and 115200 for the HA5 are sane and shouldn't be changed. 🫶
  • --straight_polarity | --reverse_polarity <small>(DS2480B)</small> — Reverse polarity of the DS2480B output transistors? Not needed for the DS9097U, but required for some other designs.
  • --link=port <small>(LINK)</small> — 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 <small>(HA7E)</small> — Embedded Data Systems HA7E adapter (and HA7S) in native ascii mode.
  • --ha5=port | --ha5=port:a | --ha5=port:acg <small>(HA5)</small> — 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 <small>(HA5)</small> — Turn on (default) or off the checksum feature of the HA5 communication.
  • --passive=port | --ha2=port | --ha3=port | --ha4b=port <small>(Passive)</small> — Passive 1-wire adapters. Powered off the serial port and using passive electrical components (resitors and diodes).
  • --8bit | --6bit <small>(Passive)</small> — Synthesize the 1-wire waveforme using a 6-bit (default) serial word, or an 8-bit word. Not all UART devices support 6 bit operation.
  • --timeout_serial=5 — Timeout (in seconds) for all serial communications. 5 second default. 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 serial conversion built in. Those 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 network 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 a 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 has 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, specific, 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 entries. Eight. Busy girl. 👑

🫶 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 discovered 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 second default and can be changed dynamically under /settings/timeout/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 actual hardware device should be simulated.
  • DS2408,DS2489 — The 1-wire device name. (Full ID cannot be speciifed in this format).

And the options:

  • --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 dynamically for each adapter under /bus.x/interface/settings/simulated/[temperature_low|temperature_high]
  • --tester=devices — Predictable address and predictable values for each read. (See the website for the algorithm).

okay that's a LOT of hardware options and we're only getting started 👀 more of this page is coming — do not scroll away 💖

🦋 w1 kernel module 🦋

ok so this one is linux-specific — it lets OWFS ride on access to bus masters that the operating system already gives you. 💅 Two things you need to know up front: root access is required, and ngl the implementation was still in progress as of owfs v2.7p12 and linux 2.6.30. So, like, it works but it's giving "under construction" energy. 🚧

Bus masters get recognized and added dynamically — the details of the physical bus master aren't accessible, but they include USB, i2c, and a bunch of GPIO designs on embedded boards. 🫶

Access is restricted to superuser because of the netlink broadcast protocol that w1 uses. Also, multitasking has to be configured (threads) at compilation time — no threads, no w1 vibes. 🧵

  • --w1 — use the linux kernel w1 virtual bus master. 🐧✨
  • --timeout_w1=10 — timeout for w1 netlink communications. It's got a 10 second default, and you can change it on the fly at /settings/timeout/w1. ⏱️

🎀 FTDI ADDRESSING 🎀

So FTDI is a brand of USB-to-serial chips and bestie they are everywhere. 🌍 If your serial device is hooked up through a USB serial dongle based on an FTDI chip, or your adapter has a built-in FTDI USB chip (hi, LinkUSB 👋), you get to use this FTDI addressing mode.

And why would you want that?? The main benefit is that we can decrease the communication delay, which gives you twice as fast 1-Wire communication in a lot of cases. literally ate. 🔥

The following values for port can be used to identify a specific FTDI port in several of the serial device options. 👇

Heads up bestie: 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 (like "003/001") inside the usb device tree (usually at /proc/bus/usb/ or /dev/bus/usb/). 📁
  • ftdi:i:<vendor>:<product> — first device with the given vendor and product id; ids can be decimal, octal (preceded by "0") or hex (preceded by "0x"). 🔢
  • ftdi:i:<vendor>:<product>:<index> — same as above, but with index being the number of the device (starting with 0) if there's more than one. 1️⃣
  • ftdi:s:<vendor>:<product>:<serial number> — the device with the 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 🌸

There's an extra format supported, for certain bus types. This one 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 they are in no way exclusive to LinkUSB. iykyk.

🎀 Permsissions 🎀

(this is the original's spelling bestie, I'm not fixing it, it's iconic 💀)

So 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
that changes the group of the raw USB node "003/001" from the default "root" to "<your user>" 🫶

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

SUBSYSTEM=="usb", DRIVER=="usb", ATTR{idVendor}=="0403", ATTR{idProduct}=="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 💜

Okay important thing: 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 it exists, the serial USB node e.g. /dev/ttyUSB0 is removed on successful starting of owserver (1). After it's terminated, un- and re-plugging the adapter, or un- and reloading of the module ftdi_sio, will recreate the serial USB node. 🔄

owusbprobe is THE tool to find the information needed for direct FTDI addressing. 👑

However 🥲 this tool might not yet be packaged in your version.

Alternatively you can also use lsusb to find the usb node your adapter is connected to, and then use lsusb again on this very node:

sudo lsusb -D /path/to/your/raw/USB/device/node  |egrep "idVendor|idProduct|iSerial"
sudo is necessary to get the value of the iSerial field, if the permissions 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 it with the URL ftp://anonymous@servernameoripaddress:portnum. 🌐

The well known ftp port, 21, will be used by default. And since this port number is in the restricted range, special permission is usually required. 😭

🌡️ TEMPERATURE SCALE OPTIONS 🌡️

  • -C, --Celsius — Celsius, bb. 🥶
  • -F, --Fahrenheit — Fahrenheit. 🇺🇸
  • -K, --Kelvin — Kelvin. 🔬
  • -R, --Rankine — Rankine. 📐

Temperature scale used for data output. Celsius is the default. 💖

Can also be changed within the program at /settings/units/temperature_scale. ✨

🫧 PRESSURE SCALE OPTIONS 🫧

  • --mbar — millibar, (default) ✅
  • --atm — atmospheres. 🎈
  • --mmHg — millimeters of mercury. 🩺
  • --inHg — inches of mercury. 📏
  • --psi — pounds per square inch. 💪
  • --Pa — pascals. 🧪

Pressure scale used for data output. Millibar is the default. 💖

Can also be changed within the program at /settings/units/pressure_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 specified 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 — the process ID of owfs — into the specified filename. Useful for startup scripts control. 📝

🎀 --background | --foreground 🎀

Whether the program releases the console and runs in the background after 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 parameters. 📂✨

🆘 HELP OPTIONS 🆘

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

🎀 -h, --help=[device|cache|program|job|temperature] 🎀

Shows a 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. Default values are shown. 🧠

  • --timeout_volatile=15 — seconds until a volatile property expires in the cache. Volatile properties 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 contents 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 💌

This whole thing was built by Paul Alfille 💖 — yes, the Paul Alfille, the one whose name is basically stitched into the fabric of this entire project. If you ever need to slide into his inbox (respectfully!! bestie behaviour only 🫶), it's paul.alfille@gmail.com.

Not me being obsessed with the fact that one person is out here gifting the world a whole filesystem, fr fr. 👑

And that's a wrap on OWFTPD(1), my love 🌸 — every option, every flag, every last byte of it. This page comes to you from the OWFS Manpage, dated 2004, living in section OWFTPD(1). Go forth and FTP responsibly, bestie 💅✨

byeeee 🦋🎀

📦 where this page comes from