Introduction

pyownet is a pure Python package for interfacing to a 1-Wire network via OWFS. A brief introduction to the main components with which pyownet interacts is given below.

1-Wire

1-Wire® is a a single contact serial interface developed by Maxim Integrated™. A typical 1-Wire network is composed by a master device and a collection of slave devices/sensors. The master device is usually connected to a host computer via a serial or USB interface, but there exist also ethernet or other network adapters.

See also

1-Wire Maxim
1-Wire technology brief from Maxim Integrated
1-Wire Wikipedia
description of the 1-Wire bus system on Wikipedia

OWFS and the owserver protocol

The “1-Wire File System”, in short OWFS, is a software system that allows to access a 1-Wire bus via a supported master device. OWFS comprises many different modules which offer different access protocols to 1-Wire data: owhttpd (http), owftpd (ftp) and owfs (filesystem interface via FUSE). Since only a single program can access the 1-Wire bus at one time, there is also a back end component, owserver, that arbitrates access to the bus from multiple client processes. Client processes can query an owserver (the program) via network sockets speaking the ‘owserver’ protocol. OWFS offers many language bindings for writing owserver clients: among others c, java, perl, php, python, which can be found in the OWFS source tree under the module/ownet directory.

See also

OWFS 1-Wire File System - development site
official OWFS site

owserver protocol brief

The owserver protocol follows a client-server paradigm: the client makes a connection to the listening socket of the owserver program and sends a message. The server replies with another message, and then either closes the connection or waits for other messages [1]. The default port 4304/tcp (and 4304/udp, although UDP is not used) is registered at the IANA as owserver service for this purpose.

Both the client and server messages are composed by a fixed length header and a variable length payload. The header structure is defined in the OWFS source tree in file module/owlib/src/include/ow_message.h as:

#include <stdint.h>

/* message to owserver */
struct server_msg {
      int32_t version;
      int32_t payload;
      int32_t type;
      int32_t control_flags;
      int32_t size;
      int32_t offset;
};

/* message to client */
struct client_msg {
      int32_t version;
      int32_t payload;
      int32_t ret;
      int32_t control_flags;
      int32_t size;
      int32_t offset;
};

#define OWSERVER_PROTOCOL_VERSION   0

The version member is set to OWSERVER_PROTOCOL_VERSION, payload is the payload length (in bytes), while server_msg.type is a constant that describes the type of request made to the server (see also Message types). client_msg.ret is a server return code (used to signal errors or abnormal situations) while control_flags are used to control various aspects of the owserver protocol (see also Flags).

After the header the actual payload is transmitted, as a (binary) stream of bytes (of length server_msg.payload or client_msg.payload).

See also

owserver network protocol
protocol specification

pyownet package contents

To time pyownet comprises a single module pyownet.protocol, which is a low-level implementation of the client side of the owserver protocol. It can be considered a replacement of the official OWFS module ownet.connection (to be found in module/ownet/python).

Although low-level, it’s use is fairly simple, due to the peculiar OWFS design, with it’s file-system like structure.

A higher-level module pyownet.sensors is under development.

Footnotes

[1]For a discussion of this type of keep-alive connection see Persistent vs. non-persistent proxy objects..