Mmmux

       

mmmux Release status: beta [box doku]
Description	A multiplexing / abstraction library for easy hardware access
Author(s)	Soeren
Platform	anything that runs GNU/Linux
License	GPL
Download	Git Repo Trac SVN

mmmux stands for Multi Media Multiplexing library, which is a small library that multiplexes hardware access to different devices (i.e. Rfm12usb and a yet-to-be-built canusb device) and forwards incoming data to all other connected clients.

Whereas the term "multi media" often refers to fancy graphical eye-candy stuff, it in this case means "connecting different transport media", such as can-bus, radio transceivers and ethernet.

The mmmux is kept as small as possible for the sake of availability. By default, the mmmux only forwards data on a local (unix) socket - in order to connect an additional medium (such as canbus), one needs to have a client that implements the hardware interface to the canbus device on one side and the mmmux protocol on the other - the same holds for radio transceivers etc.

API

From the programmer's point of view, the API is pretty simple and not hard to understand. First of all, you need to initialize a mmmux context with mmmux_init(). Right after that, you can send and receive data from this context with the functions mmmux_send() and mmmux_receive().

What the mmmux implementation in the background does, is fork a process (server) that handles incoming data and forwards it to the device or connected clients respectively. If the server is already running, thus was invoked by another application using the mmmux library, the mmmux_init() function will just connect to the existing server.

When starting, the process searches for hardware devices it can get a grab on and tries to use them. Whenever the daemon discovers a new device, it starts another process (hardware handling task) in order to process data from and to the device without delays.

Migration from current Infrastructure

In our current implementation we have a canbus daemon (cand) that connects the canbus transceiver hardware with the tcp protocol. Programs that need to talk to canbus devices connect via tcp to the cand, which then forwards data from and to the bus.

In order to connect our current infrastructure to the mmmux, a proxy program connects the cand service with the mmmux server. This way we can migrate the current infrastructure step by step.

Operation scenarios

The mmmux may be used to multiplex access to a single media transceiver - such as rfm12usb. This way one may use a single hardware device with several different applications at a time - this was the primary implementation goal.

It may as well be used to forward data between different media and can easily connect canbus-speaking devices with radio transceivers.

It can be used to connect distant canbus/radio networks with one another - for example connecting two canbus networks via ethernet in scenarios where otherwise the cable length would be over the specifications for safe operation.

Security

Of course this software is insecure and contains lots of bugs - especially at this early stage. Depending on the system's configuration, it may be necessary for a user to start the mmmux implementation as privileged user (root in most cases). Whenever possible, the implementation grabs a handle to the device and then chroot's itself to a temporary directory and changes GID and UID to some random number (> 30.000).

As far as local sockets are concerned, neither encryption, nor further access control is applied (the latter is planned). In order to apply some level of authentication, you may want to manually set permissions to the socket (/tmp/mmmuxd.sock) accordingly.

Adding new devices

In order to add a new hardware device handler, one needs to implement some or all of the 5 functions listed below. For reference, you may as well have a peek into muxd_hw_rfm12usb.c and see how these functions are written, what their prototypes are and what they do.

Initialization routine

This function is called when a new device is added or found. The function is optional and may only be of use for hardware devices that need initialization.

Send & Receive routines (aka rx and tx)

When data arrives from the client side, the send function is called. Likely, when data is available from the device, the rx function is used to gather it and send it to connected clients. Note that the rx function should be non-blocking and return 0 when no data is available. Values < 0 from both functions indicate errors and will result in a call to the close function, followed by the termination of the hardware task.

Close function

This function is used to properly close the connection to the device, turn it off and do whatever you need to do in order to close the link to the device.

Find function

The find function is used to discover hardware devices - i.e. scan the usb bus and search for compatible devices. This function should then call mmmux_hw_add() in order to let mmmux know that there's a new device available. Mmmux will then start the hardware task and poll for data frequently.