danielinux / ttybus

A simple TTY multiplexer.

TTYBUS project

Copyright (c) 2010-2021 Daniele Lacamera [email protected] and other contributors (see git log for details)

dpipe command - copyright 2003 Renzo Davoli

Daemonization option - copyright 2020 Frank Sautter [email protected]

OVERVIEW

The TTYBUS project is a toolkit that provides tty device virtualization, multiplexing, spoofing and sharing among unix processes. It allows users to connect their real and virtual terminals (including real serial devices) to a shared, non-reliable bus, and then to virtually any input/output stream.

LICENSE

TTYBUS comes without any warranty and it is released under the terms of the GNU/GPL v.2

IDEA

TTYBUS steals the architecture concept from VDE (Virtual Distributed Ethernet) design. The working scheme is quite simple: Users can connect their ttys together in a virtual bus, then all data sent and received from any of the devices connected to the virtual bus is echoed to all other devices.

This includes real and virtual tty devices, with the possibility to create fake devices using posix pseudo-terminals.

COMPONENTS

tty_bus

Creates a new tty_bus running on the system, at a given bus path specified with the -s option. The command creates the bus and exposes a unix socket at the given path. Once the path has been created, any device can be plugged in using the other toolkit's commands. The -d option deamonizes the process and detaches it from the terminal.

tty_plug

Connects STDIN/STDOUT of the current terminal to the tty_bus specified with the -s option. Eventually the -i option can be specified to add an init string to be passed to process stdout before it's connected to the tty_bus. The -d option deamonizes the process and detaches it from the terminal.

tty_fake

Creates a new pseudo-terminal devices connected to the tty_bus specified with the -s option. If the given path for the fake device already exists, tty_fake can be forced to replace it with the -o option. The -d option deamonizes the process and detaches it from the terminal.

tty_attach

Open a real (existing) tty and connects it to the tty_bus specified with the -s option. Eventually the -i option can be specified to add an init string to be passed to the real tty device before it's connected to the tty_bus. The -d option deamonizes the process and detaches it from the terminal.

dpipe

Taken from the VDE project, allows two unix processes to communicate each-other by attaching each process' STDOUT stream to the other one's STDIN.

Please refer to each command's help for usage notes, using the -h option .

EXAMPLES

Use case 1

Multiplexing serial input only or output only device attached to /dev/ttyS0, for use with multiple applications.

1. Create a new tty_bus called /tmp/ttyS0mux:

   tty_bus -d -s /tmp/ttyS0mux

2. Connect the real device to the bus using tty_attach:

   tty_attach -d -s /tmp/ttyS0mux /dev/ttyS0

3. Create two fake /dev/ttyS0 devices, attached to the bus:

   tty_fake -d -s /tmp/ttyS0mux /dev/ttyS0fake0

   tty_fake -d -s /tmp/ttyS0mux /dev/ttyS0fake1

4. Start your application and force it to use the new serial device for input or output

   /bin/foo /dev/ttyS0fake0 &

   /bin/bar /dev/ttyS0fake1 &

Both application will read (or write) from the same serial device.

CAUTION: All data written on each of the two fake devices will be echoed on the other one too.

Use case 2

Create fake NMEA devices from your running gpsd daemon.

1. Create the bus:

   tty_bus -s /tmp/gpsmux

2. Use dpipe, tty_plug and netcat to connect tcp socket to gpsd daemon. Send 'r' as init string to get NMEA flow from the socket:

   dpipe tty_plug -s /tmp/gpsmux -i "r" = nc -c ip.address.of.gpsd 2947

3. Create a fake gps device

   tty_fake -s /tmp/gpsmux /dev/gps0

4. Connect your legacy serial, non gpsd-compatible, nmea application to the fake device /dev/gps0

   /usr/local/games/stupid_nmea_app /dev/gps0

Use case 3:

Remote serial device via SSH tunnel. Host mars has a serial device connected on /dev/ttyUSB0, which must be accessed and used from host venus.

1. Create two tty_busses, one per machine.

   mars:$ tty_bus -s /tmp/exported_ttybus

   venus:$ tty_bus -s /tmp/remote_ttybus

2. On mars, attach the device to the local bus:

   mars:$ tty_attach -s /tmp/exported_ttybus /dev/ttyUSB0

3. On venus, prepare the fake tty device, on the same path, temporarly overriding the local /dev/ttyUSB0 device:

   venus:$ tty_fake -s /tmp/remote_ttybus -o /dev/ttyUSB0

4. Connect the two buses on the two hosts, using remote ssh command and tty_plug:

   venus:$ dpipe tty_plug -s /tmp/remote_ttybus = ssh mars tty_plug -s /tmp/exported_ttybus

From now on, the /dev/ttyUSB0 on venus is actually the device connected on mars. If it existed before being overridden, the original /dev/ttyUSB0 is restored once the tty_fake process on venus gets killed.

ttybus's Issues

fix for vmware VMs

ttybus/tty_attach.c

Line 100 in 32e9a9e

realdev = open(devname, O_RDWR);

-       realdev = open(devname, O_RDWR);
+       realdev = open(devname, O_RDWR|O_NOCTTY|O_NONBLOCK);

Full duplex communications

I'm not sure if this is a bug or not, but I am using scenario #1 where I have a program communicating with a hardware serial device and I want to clone the hardware port so I can both monitor and communicate with the hardware device along with the program I wrote.

So far, I followed the instructions to create a ttyS1mux, attached it to my ttyS1 hardware port, and then created two fake ports, ttyS1fake0 and ttyS0fake1. My question is should I be able to do full-duplex communications between all three connections? I found that I could send serial data through either of the fake ports to the real port, but for some reason, data sent through the real port doesn't arrive to either of the fake ports. Is this by design or is there a way to get bidirectional communications?

Usage on simulated serial device

First of all thank you for this tool, I'm trying to use it on a simulated serial device, that writes on /dev/ptmx and output in a pseudoterminal /dev/pts/[number], and I'd like to be able to read this device from multiple processes but when i link the real device to the fake tty the simulated devices just stop. could this be because of the original port being a simulated device and not a real device?

How to install and use on linux?

How to install and use on linux?

ttybus losing some bytes

I think I understood what was going on with my application.
The tty_mux socket might be filling its buffer after some time, and then things do not work well anymore.

Found out that the BUFFER_SIZE is 4096.

ttybus currently doesn't have a way to change this value from the command line, but I am not sure yet if increasing it will make any difference since my app will be running for a long time and the issue will eventually happen again

Do you have a suggestion for what I could do in this case?

I started my issue here, #14 (comment). Well, I am opening a new issue instead of hijacking the other one.

tty_fake not working after disconnecting and reconnecting to fake serial port

After setting correctly a bus with a real serial port and 2 fake port (can see the data in two independent terminal via miniterm/screen/a specific software), if the connection ttyS0fake0 (same with fake1) is closed, it cannot be reopen. It is necessary to kill the tty_fake process and restart it:

tty_bus -s /tmp/ttyS0mux

on a different terminal:

tty_attach -s /tmp/ttyS0mux /dev/ttyUSB0

on a different terminal:

tty_fake -s /tmp/ttyS0mux /tmp/ttyS0fake0 $
tty_fake -s /tmp/ttyS0mux /tmp/ttyS0fake1

on a different terminal:

miniterm /tmp/ttyS0fake1 19200

then if closing the miniterm and trying to reopen it with the same command, it won't work

Losing data

Hi, @danielinux

I am using ttybus to split the serial stream of data from a USB to 2 applications.

When I use the USB device directly my application works nicely parsing the data however when I use ttybus I have some issues parsing the data that comes from the virtual device. For instance, 60% to 80% of the data cannot be parsed for some reason I could not understand why.

I am not sure what is happening yet, but I think ttybus may be losing some data, somehow.

Do you know if there is any way that I can debug the ttybus stream somehow?

Any idea will help me since I currently don't know what is the issue. Thank you.

Problem reading from one serial device with two apps

I would like to use your tool to read from one physical serial device with two apps and both of them seing the same data read. One of those apps will also write to the port, the other won't.

I've set everything up according to your use case example 1, however when I start the app which will be writing and direct it to fake device nr 1 I get lots of communication errors in the log:

2021.06.24 23:54:17 3: SCC: Unknown code ? (? (? is unknown) Use one of m B b C F i A Z G MX21 is  , help me!
2021.06.24 23:54:19 3: SCC: Unknown code  of m B b C F i A Z G M T011234, help me!
2021.06.24 23:54:19 3: SCC: Unknown code Y R T , help me!
2021.06.24 23:54:19 3: SCC: Unknown code ? (? (? is u? ( Y R T V W X e f * l tiG, help me!
2021.06.24 23:54:19 3: SCC: Unknown code ? (? (? (? is unknoT011234 in , help me!
, help me! 23:54:19 3: SCC: Unknown code ? (wn) Use one o fnknown) Use one of m B b C F i A Z G MX21 is  
2021.06.24 23:54:19 3: SCC: Unknown code ? ( Y R T V W X e f * l tiG, help me!
2021.06.24 23:54:19 3: SCC: Unknown code ? (, help me!
2021.06.24 23:54:19 3: SCC: Unknown code ? ( B b C F i A Z G M Y R T V W X e f * l t u x is unknown) Use one of m B b C ? (? (? is unknoT011234 in , help me!
2021.06.24 23:54:19 3: SCC: Unknown code ? (wn) Use one o f, help me!
2021.06.24 23:54:20 3: SCC: Unknown code ? ( B b C F i A Z G M Y R T V WF i A Z G M T0113 , help me!
2021.06.24 23:54:20 3: SCC: Unknown code ? (? (? (? is unknown) Use one X e f * l t u x is unknown) Use one of m B b C F i A Z G M T0113 , help me!
2021.06.24 23:54:20 3: SCC: Unknown code ? (? ( Y R T V W X e f * nX, help me!
2021.06.24 23:54:20 3: SCC: Unknown code ? (? (? (?8, help me!
2021.06.24 23:54:20 3: SCC: Unknown code ? (? (? (? is unknown) Use one of m B b C F i A Z G MX21 is    (? is unknoT011234 iG, help me!

Basically the physical device has a very simple CLI and sends and receives plain text data ending with \r\n - but something in the ttybus seems to annoy it. I've started every component without the daemon option to potentially see any issue but there is no output in any of the tty_* tools apart from tty_bus.

The whole thing is about a "CUL" device receiving 868 MHz data, parsing it and returning it to an app as a plaintext string. It is used with a home automation system called fhem (fhem.org). The physical device is the CUL SCC from busware.de

Any idea what could be the problem?

Feature Request: Force a tty_fake to be 'read only'

Obviously I can just choose to not write to the port, but for the sake of safety in certain applications, it helps to know that there is a guardrail in place. I recommend adding a '-r' command line option for tty_fake that will lock out writing to the port from that fake tty.

Cannot get the right PID from tty_fake

Hi, I am running this code:

user@pc: $ tty_fake -d -s "/dev/my_tty_mux" "/tmp/my_tty_fake"

user@pc: $ echo "PID=$!, ST=$?"
PID=31163, ST=0

user@pc: $ ps aux | grep tty_fake
main     31429  0.0  0.0   1884    68 ?        Ss   09:12   0:00 tty_fake -o -d -s /dev/my_tty_mux /tmp/my_tty_fake
main     31457  0.0  0.0   7448   572 pts/0    S+   09:14   0:00 grep --color=auto tty_fake

The variable $! is giving me this PID 31163 no matter what I do. But the actual value is different, this time it is 31429. Is there any reason for that? Is there a way to get the right PID straight from the tty_fake command without having to process the ps command, for instance?

Documentation: Explain "non-reliable" in README.md

The README.md file currently states "a shared, non-reliable bus" and this is scaring off some of my coworkers from adopting this as a solution to a current problem we have. Could you explain somewhere in the documentation what the meaning of "non-reliable" is in this context? Is it just that it can't prevent corruption when multiple devices send simultaneously? If that's all it is, then my other current issue #13 would make the bus reliable by locking out writing on all but one fake_tty.

Usage Problems

Hi i just tried to use your Tool, but if i
tty_bus -s /tmp/ttyS0mux

It just Outputs
Creating bus: /tmp/ttyS0mux

And never end... What am i doing wrong ? I just cloned the git used make and make install..
Thanks for an answer..
Tobi