DEVICE(1so)

📦 version 3.2_p4, in alpine 3.24, nixos 26.05, nixpkgs unstable

💅 DEVICE(1so) — or, how to pick your 1-wire bus master bestie ✨

Okay so listen — these options are literally about choosing which device (the bus master, aka the main character) connects your computer to the 1-wire bus. The 1-wire slaves hang out on the 1-wire bus, and the bus master is the one that plugs into a port on your computer and runs the whole show. The bus master can be an actual physical device, the kernel w1 module, or an... (and yes, the original sentence really does trail off like that, we love a cliffhanger 💀).

🚨 At least one device option is required. There is no default. Periodt.

You can list more than one device and all of them get used — it's a logical union unless you go exploring the /bus.n/ directories yourself. Hope that clears it up bestie 🫶

🔒 SECURITY VIBE CHECK

Linux and BSD are strict queens — they enforce a security policy that restricts access to hardware ports. You must have sufficient rights to access the given port, or the access will silently fail (the worst kind of fail, no cap 😭).

🎀 THE SERIAL GANG 🎀

port specifies a serial port, e.g. /dev/ttyS0, or a USB port accessed as a serial port, e.g. /dev/ttyUSB0. And 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 below (it's giving ✨bonus content✨).

  • -d port | --device=port — (DS2480B) The 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. Changes details of bus timing (see DS2480B datasheet). Some devices, like the [redacted by the original text], cannot work with this.
  • --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 family and in the interface/settings directory. The 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 family and --baud=9600... er, and 115200 for the [others]) are sane and shouldn't be changed. Trust the defaults, bestie 💖
  • --straight_polarity | --reverse_polarity — (DS2480B) Reverse polarity of the DS2480B output transistors? Not needed for the DS9097U, but required for some other designs. Iconic little toggle 🦋
  • --link=port — (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) adapter (and [companions]) in native ascii mode.
  • --ha5=port | --ha5=port:a | --ha5=port:acg — (HA5) multidrop 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 — patience, queen 🧚).
  • checksum toggle — Turn on (default) or off the checksum feature of the HA5 communication.
  • --passive=port | --ha2=port | --ha3=port | --ha4b=port — (Passive) Passive 1-wire adapters. Powered off the serial port and using passive electrical components (resistors and diodes). Synthesize the 1-wire waveform using a 6-bit (default) serial word, or 8-bit word. Not all UART devices support 6 bit operation (rude of them, honestly).
  • --timeout_serial=5 — Timeout (in seconds) for all serial communications. 5 second default. Can be altered dynamically under [the settings directory]. ⏰

🦋 THE USB GANG 🦋

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 — these are supported by the serial bus master protocol. Slay for backwards compatibility 💅

  • DS2490-based bus master — like the DS9490R. The moment you've been waiting for 👑
  • Use the second USB bus master. — (The order isn't predictable, however, since the operating system does not consistently order USB devices. Classic OS behavior, no notes 💀)
  • Use all the USB devices. — all of them. every single one. 🌈
  • USB waveform timing option — Changes the details of 1-wire waveform timing for certain network configurations.
  • Willy Robion's alternative USB timing. — the icon himself 🎀
  • USB timeout option — Timeout for USB communications. This has a 5 second default and can be changed dynamically under [the settings directory].

🌸 I2C, THE CHIP-TO-CHIP GOSSIP 🌸

I2C is 2 wire protocol used for chip-to-chip communication. The bus masters [DS2482-based and friends] can specify (via pin voltages) a subset of addresses on the i2c bus. Those choices are 0,1,2,3 → 0x18,0x19,0x1A,0x1B and 4,5,6,7 → 0x1C,0x1D,0x1E,0x1F (DS2482-800 only) for i2c masters.

  • -d port | --device=port — have the form. This simple form only permits a specific [address] and the first available.
  • --i2c=port | --i2c=port:i2c_address | --i2c=port:ALL — Specific i2c, and the [address] is either the first, specific, or all of them. The [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 [have] 8 1-wire buses and so will generate 8 entries. Obsessed with the thoroughness tbh 🌟

🧚 NETWORK BUS MASTERS (long distance relationship era) 🧚

These bus masters communicate via the tcp/ip network protocol and so can be located anywhere on the network. The [address] is of the form tcp_address:port — e.g. 192.168.0.1:3000 or localhost:3000.

  • LinkHubE — network LINK adapter by HA7Net.
  • HA7Net network 1-wire adapter — with specified tcp address or discovered by udp multicast. By [default]... specific timeout for HA7Net communications (60 second default).
  • Etherweather adapter — the weather girlie of the lineup 🌦️
  • -s network_address | --server=network_address — Location of an owserver program that talks to the 1-wire bus. The default port is 4304.
  • network timeout option — Timeout for network bus master communications. This has a 1 second default and can be changed dynamically under [the settings directory].

🎀 SIMULATED DEVICES (fake it till you make it) 🎀

Used for testing and development. No actual hardware is needed. Useful for separating the hardware development from the rest of the software design. A literal dream, honestly 😭

[The device list] 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 (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 specified in this format).
  • Random address and random values for each read. — The device ID is also random (unless specified).
  • Specify the temperature limits for the 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 [the settings directory].
  • Predictable address and predictable values for each read. — (See the website for the algorithm. iykyk 💫)

👑 THE LINUX KERNEL W1 BUS MASTER 👑

This is 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 (so like, vintage vibes).

Bus masters are recognized and added dynamically. Details of the physical bus master are not accessible, but they include USB, i2c and a number of GPIO designs on embedded boards. Access is restricted to superuser due to the netlink broadcast protocol employed by w1. Multitasking must be configured (threads) on the compilation.

  • Use the linux kernel w1 virtual bus master. — the plug-and-play queen ✨
  • w1 netlink timeout option — Timeout for w1 netlink communications. This has a 10 second default and can be changed dynamically under [the settings directory].

💜 FTDI ADDRESSING (the deep lore) 💜

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. It ate, no cap 🔥

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 (check before you come for me 🙈).

  • 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 decimal, 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). 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. 🫶

🔐 PERMISSIONS, BABE (you got this)

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

This changes the group of the raw USB node "003/001" from default "root" to "<your user>". Bestie-tier solution 💖

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. Automation queen 👑

⚠️ IMPORTANT RAW USB NODE WARNING ⚠️

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 its termination, un- and re-plugging the adapter, or un- and reloading of the module ftdi_sio, will recreate the serial USB node. Just so you're not surprised, bestie 💀

🔍 FINDING YOUR FTDI INFO

owusbprobe is THE tool to find the information needed for direct FTDI addressing. However, this tool might not yet be packaged in your version (rude).

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 iSerial field, if the permissions are still unchanged.

🌟 EXAMPLES (the moment you've been waiting for) 🌟

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

owserver -d ftdi:s:0x0403:0x6001:A800bXHr

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

owserver --link=ftdi:A800bXHr

Both icons, both slay ✨

💀 Quick recap of the big warnings: no default device (pick one!), silent failure if you lack port permissions, root required for the kernel w1 master, threads must be configured for w1, FTDI mode accesses the raw USB node and removes the serial USB node on startup. Don't say I didn't warn you 🫶

Source and version: this little love letter is from the owfs v2.7p12 era, dated alongside linux 2.6.30 — vintage but still glowing ✨💜 Slay responsibly, bestie!

📦 where this page comes from