pyaudible 1.1.0b3

A Python library for sending and receiving data using audible sound.

PyAudible 1.1.0

A Python library for sending and receiving data using audible sound. PyAudible includes a transmitter and a receiver module that could be implemented on multiple devices, enables the transmission of small amounts of data between separated systems in the vicinity.

The library implements a Multi-channel Carrier Modulation protocol, allows a configurable transmitting speed between 5 - 20 bytes/sec. It uses Cyclic Redundancy Check (CRC) to ensure reliable data delivery.

The transmitter and the receiver provide simplified Python interface that could be easily integrated in various other projects, possible scenarios includes:

• Smart Home Appliances (IoT)
• Data Broadcasting
• Device Pairing
• Electronic Key Sharing

This README file provides a walkthrough of the project, include a quickstart, brief documentation and evaluation.

Other docs can be found at:

• Full Documentation
• Protocol Details
• Test & Evaluations

Project Roadmap

Quickstart

Tested on Python 3.8

Requirements

• Python 3.6+
• PyAudio 0.2.11+ (speaker access required for the transmitter, microphone access required for the receiver)
• Numpy 1.18.5+

Installation

With required dependencies installed, use pip install pyaudible to download and install PyAudible.

To validate the installation, run the following code and it should print the version of the transmitter, receiver, PyAudio and PortAudio to the console.

from pyaudible import transmitter, receiver
transmitter.print_transmitter_version()
receiver.print_receiver_version()

After the installation, keep following the examples provided below or refer to the full documentation for more information.

Examples and Demos

The following examples will demonstrate the basic transmission protocol of PyAudible. More examples could be find in the full documentation.

Example: Modulate and Transmit Data

In this example we converted a message to electrical signals and generated the modulated audio file.

"""PyAudible Example: Modulate and Transmit Data"""

from pyaudible import transmitter

# instantiate the transmitter
tx = transmitter.Transmitter(speed = 'fast', volume = 1.0)

# define the message to be transmitted
message = 'Hello World!'

# define the filename
filename = 'transmitter_sample.wav'

# modulate the message and store the modulated signal to an audio file
tx.modulate_to_file(message, filename)

Example: Receive and Demodulate Data (Blocking Mode)

In this example we set up a PyAudible Receiver and kept it on standby for 30 seconds. If the transmitted signal was played during the standby time, it would capture and convert the signal back to text.

"""PyAudible Example: Receive and Demodulate Data (Blocking Mode)"""

from pyaudible import receiver

# instantiate the receiver
rx = receiver.Receiver(sensitivity = 'medium',
                        speed = 'auto')

# active the receiver for 30 seconds
retrieved_data = rx.read_block(30)

Protocol Overview

This section briefly demonstrated the transmission protocol, however, a full detailed explanation could be found in Protocol Details.

Figure 1: Multi-channel Carrier Modulation

The protocol utilises a Frequency-Shift Keying (FSK) technique to modulate the raw data into an eight-channel carrier signal Channel_01 - Channel_08. Each carrier channel transmits data by switching the frequency within a range of 16 candidate frequencies FC(0) - FC(15) (Shown in Figure 1). And each candidate frequency represents a 4-bit chunk (0000, 0001...1111). Therefore, 8 x 16 = 128 candidate frequencies are equally spaced between 1238 Hz to 6965 Hz, divided by dF = 43.0 kHz. The original data is converted into binary representations, and then it is encapsulated into packets of 8, 16 or 32 bits per unit time (depending on the transmission rate), then transmitted via 2, 4 or 8 channels.

To handle the transmission signal, the receiver maintains seven Status Flags to signifying the status of the current connection, shown in Figure 2 below.

Figure 2: Receiver Handling Behaviours

The beginning and ending bits of the transmission sequences are the Activating and Terminating Sound Mark. Each part of the sound mark contains essential session descriptors to establish and terminate the connection, shown in Figure 3 below. These descriptors also maintain important functionalities include flow control and noise resistance mechanism.

Figure 3: Sound Marks Structure

Documentation

Full documentation provided in Documentation.

Alternatively, the documentation can be generated and viewed via __doc__, for example print(receiver.Receiver.read_block.__doc__).

Test and Evaluation (Overview)

Full experimentation designs and the evaluation results provided in Test & Evaluation document.

The evaluations of the system were conducted along with the development. Phase I Evaluation assessed the reliability of the noise resistance mechanism in different noise conditions, and verified that the system can achieve at least 90% reliability with a transmission rate at 20 bytes/sec. Phase II Evaluation gave a statistical analysis on the reliability with respect to the transmission speed and the signal to noise ratio. The following Speed-Rate-Reliability Lookup Table is taken from the results of Phase II Evaluation, which could help users to decide transmission settings based on noise situations:

Transmission Speed	Transmission Success Rate	Reliability
Signal to Noise Ratio = 1.2
5 bytes/sec (slow)	0.20	0.80
10 bytes/sec (medium)	0.11	0.55
20 bytes/sec (fast)	0.07	0.38
Signal to Noise Ratio = 1.5
5 bytes/sec (slow)	0.72	0.90
10 bytes/sec (medium)	0.54	0.80
20 bytes/sec (fast)	0.47	0.77
Signal to Noise Ratio = 2
5 bytes/sec (slow)	0.99	1.00
10 bytes/sec (medium)	0.73	0.97
20 bytes/sec (fast)	0.66	0.90
Signal to Noise Ratio = 2.5
5 bytes/sec (slow)	0.99	1.00
10 bytes/sec (medium)	0.95	1.00
20 bytes/sec (fast)	0.90	0.97

Speed - Rate - Reliability Lookup Table

Latest Updates

04.01.21 V1.1.0
Compatible to any audio backends as long as it provides buffered audio analysis.

Full update history provided in Updates.

Acknowledgment

This project is carry out in comply with the guidelines of COMP390 module, as a key element of the Honours Year Project.

License

MIT