dendrotox is a Python module designed to enable Python code to interact with the Tox distributed communications network, including for the purposes of scripts communicating with people or other scripts. It uses a 2015 version of ToxCore and ratox for interfacing with the Tox network and megaparsex for parsing.

In particular, dendrotox interacts with the filesystem provided by the FIFO Tox client ratox. dendrotox also provides functionality to send and receive messages, to parse input, to send files, to request confirmations, to provide information such as IP address and weather information, and to run arbitrary commands, including functionality to launch reverse-SSH connections and to restart a script.

Tox

Tox is a peer-to-peer instant-messaging and video-calling protocol that has end-to-end encryption.

The following is a typical Tox ID that one contact can give to another contact in order to connect:

56A1ADE4B65B86BCD51CC73E2CD4E542179F47959FE3E0E21B4B0ACDADE5185520B3E6FC5D64
<--------------------------------------------------------------><------><-->
                                ^                                  ^      ^
                                |                                  |      |
                                |                                  |      |
                            PUBLIC KEY                        NOSPAM      CHECKSUM

The Tox ID is a public key (64 characters), a nospam value (8 characters) and a checksum (4 characters) concatenated in hexadecimal format. The result is a 76 character string.

The public key is generated by the NaCl (Networking and Cryptographic library) crypto_box_keypair function. It is 32 bytes (64 hexadecimal characters). The nospam value is a generated pseudorandom number appended to the public key. A connect request sent without the correct nospam value is ignored. The nospam value can be changed at any time without affecting the public key, stopping all requests to the current ID, in order to fight spam. The checksum is a simple XOR checksum of the public key and the nospam value. It is used to quickly verify the integrity of the Tox ID.

Because Tox has no central servers, it is necessary to know a node that is already in the network before a client can be connected suffessfully. Some nodes are listed here.

setup

sudo apt install    \
    autoconf        \
    autotools-dev   \
    automake        \
    build-essential \
    checkinstall    \
    check           \
    cmake           \
    festival        \
    git             \
    libtool         \
    libsodium-dev   \
    sox             \
    yasm

mkdir ~/Tox
cd ~/Tox

Install FFmpeg.

sudo apt install lame libmp3lame-dev
wget http://ffmpeg.org/releases/ffmpeg-3.3.2.tar.bz2
tar -xvf ffmpeg-3.3.2.tar.bz2
cd ffmpeg-3.3.2
./configure --enable-libmp3lame
make -j$(nproc)
sudo make install
cd ..
rm ffmpeg-3.3.2.tar.bz2
rm -rf ffmpeg-3.3.2

Set up Festival, eSpeak, Pico TTS and deep_throat for speech capabilities.

sudo apt install     \
    festival         \
    espeak           \
    libttspico0      \
    libttspico-utils \
    libttspico-data
sudo pip install deep_throat

Install the Sodium crypto library.

git clone https://github.com/jedisct1/libsodium.git
cd libsodium
git checkout tags/1.0.3
./autogen.sh
./configure
make check
sudo checkinstall --install --pkgname libsodium --pkgversion 1.0.0 --nodoc
sudo ldconfig
cd ..

Install the libvpx codec.

git clone https://chromium.googlesource.com/webm/libvpx
cd libvpx
git checkout tags/v1.4.0
./configure --enable-shared --disable-static
make -j$(nproc)
sudo make install
cd ..

Install ToxCore.

wget --content-disposition https://codeload.github.com/irungentoo/toxcore/tar.gz/api_old_version
tar -xvf toxcore-api_old_version.tar.gz
cd toxcore-api_old_version
autoreconf --install --force
mkdir _build
cd _build
../configure
make -j$(nproc)
sudo make install
sudo ldconfig
cd ../..

Install ratox.

git clone https://github.com/wdbm/ratox.git
cd ratox
make -j$(nproc)
sudo make install

Install dendrotox.

sudo pip install dentrodox

When ratox is launched for the first time, it creates a Tox profile file .ratox.tox at the working directory to store Tox profile details. While running, the file id contains the Tox ID.

examples

dendrotox is imported and launched in the following way:

import dendrotox
dendrotox.start_messaging()
print("Tox ID: " + dendrotox.self_ID())

sending messages

A message can be sent to a contact in the following way, where a contact is specified using a string containing their Tox ID:

dendrotox.send_message(contact = contact, text = "oohai")

A message can be sent to multiple contacts in the following way, where contacts are specified as a list of strings containing contacts' Tox IDs.

dendrotox.send_message(contacts = [contact_1, contact_2], text = "sup")

A message can be sent to all contacts in the following way.

dendrotox.send_message(contacts = "all", text = "yo yo yo")

receiving messages

A list of unseen messages received recently can be accessed in the following ways:

messages = dendrotox.received_messages()
print(messages[0].sender())

message = dendrotox.last_received_message()
print(message)

sending sound calls

A sound call can be sent to a contact in a few ways. One way is by sending a sound file:

dendrotox.send_call(contact = contact, filepath = "alert.wav")

Another way is by using synthesized speech:

dendrotox.send_call_synthesized_speech(contact = contact, text = "This is an alert.")

Another way is by using a microphone:

dendrotox.send_call(contact = contact, record = True)

Sending a sound call by using a microphone can feature a record duration specification in order to ensure that the process does not hang:

dendrotox.send_call(contact = contact, record = True, duration_record = 30)

receiving sound calls

A sound call can be received from a contact in a few ways. One way is by using speakers:

dendrotox.receive_call(contact = contact)

If a contact is not specified, the first contacted identified as calling is used to receive a call:

dendrotox.receive_call()

Another way is by receiving a sound file:

dendrotox.receive_call(filepath = "call.wav")

See module code and example bot code for more advanced usage, including calls, message parsing, confirmations and running commands.

dendrotox_alert.py

The script dendrotox_alert.py is a command line script that can be used to send a message to contacts. It attempts to connect with any specified contacts before attempting to send a message to them. If no contacts are specified, it attempts to send a message to all known contacts.

dendrotox_alert.py --text="alert"

future

Under consideration is speech-to-text for receiving calls.