From 09afd32f0bcc0223e72b4a60579c27befec2a83a Mon Sep 17 00:00:00 2001 From: Roman Zeyde Date: Wed, 24 Sep 2014 09:32:29 +0300 Subject: [PATCH] README: update for new amodem script. --- README.md | 119 +++++++++++------------------------------------------- 1 file changed, 24 insertions(+), 95 deletions(-) diff --git a/README.md b/README.md index 8268508..625bb68 100644 --- a/README.md +++ b/README.md @@ -3,17 +3,17 @@ [![Build Status](https://travis-ci.org/romanz/amodem.svg?branch=master)](https://travis-ci.org/romanz/amodem) [![Coverage Status](https://coveralls.io/repos/romanz/amodem/badge.png?branch=master)](https://coveralls.io/r/romanz/amodem?branch=master) -## Description +# Description This program can be used to transmit a specified file between 2 computers, using a simple audio cable (for better SNR and higher speeds) or a simple headset, allowing true air-gapped communication (via a speaker and a microphone). -The sender side uses `send.py` script to modulate the input data into an 32kHz -audio file, which is played to the sound card, using `aplay` Linux utility. +The sender modulates an input binary data file into an 32kHz audio file, +which is played to the sound card, using `aplay` Linux utility. The receiver side uses `arecord` Linux utility to record the transmitted audio -to an audio file, which is demodulated concurrently by the `recv.py` script. +to an audio file, which is demodulated concurrently into an output binary data file. The process requires a single manual calibration step: the transmitter has to find maximal output volume for its sound card, which will not saturate the @@ -28,138 +28,67 @@ The modem is using OFDM over an audio cable with the following parameters: This way, modem achieves 48kpbs bitrate = 6.0 kB/s. -A simple Reed-Solomon ECC is used, with (255,245) rate = ~3.9% overhead. +A simple CRC-32 checksum is used for data integrity verification on each 1KB data frame. # Installation -## Required packages +Run the following command (will also download and install `numpy` and `bitarray` packages): -Make sure the following Python packages are installed: - - $ sudo pip install numpy reedsolo bitarray + $ sudo pip install amodem For graphs and visualization (optional), install: $ sudo pip install matplotlib -## Calibration +# Calibration Connect the audio cable between the sender and the receiver, and run the following scripts: - On the sender's side: ``` -~/sender/amodem $ ./calib.py send +~/sender $ amodem send --calibrate ``` - On the receiver's side: ``` -~/receiver/amodem $ ./calib.py recv +~/receiver $ amodem recv --calibrate ``` -The sender computer's output audio level should be increased, until the -received **amplitude** and **peak** values are not higher than 0.5, while -the **coherence** is 1.0 (to avoid saturation). +Increase the sender computer's output audio level, until the +received **amplitude** and **peak** values are not higher than 0.5, +while the **coherence** is 1.0 (to avoid saturation). -See http://youtu.be/iCg1tepGz10 for calibration demo. +# Testing -## Testing - -See http://youtu.be/94yS3IZmtho for usage demo. - -- Prepare the sender: +- Prepare the sender (generate random binary data file to be sent): ``` -~/sender/amodem $ dd if=/dev/urandom of=data.send bs=125kB count=1 status=none -~/sender/amodem $ ./send.py audio.pcm -2014-08-01 21:00:06,723 INFO Running MODEM @ 48.0 kbps -2014-08-01 21:00:06,773 INFO 3.210 seconds of training audio -2014-08-01 21:00:07,712 DEBUG 8.886 seconds of data audio -2014-08-01 21:00:08,714 DEBUG 14.941 seconds of data audio -2014-08-01 21:00:09,712 DEBUG 20.994 seconds of data audio -2014-08-01 21:00:10,381 INFO 21.846 seconds of data audio, for 125.000 kB of data -~/sender/amodem $ sha256sum data.send -008df57d4f3ed6e7a25d25afd57d04fc73140e8df604685bd34fcab58f5ddc01 data.send +~/sender $ dd if=/dev/urandom of=data.tx bs=125kB count=1 status=none +~/sender $ sha256sum data.tx +008df57d4f3ed6e7a25d25afd57d04fc73140e8df604685bd34fcab58f5ddc01 data.tx ``` - Start the receiver: ``` -~/receiver/amodem $ ./wave.py record rx.int16 & -~/receiver/amodem $ ./recv.py data.recv -2014-08-01 21:00:30,068 INFO Running MODEM @ 48.0 kbps -2014-08-01 21:00:30,068 DEBUG Skipping first 0.100 seconds +~/receiver $ amodem recv >data.rx ``` - Start the sender: ``` -~/sender/amodem $ ./wave.py play audio.pcm +~/sender $ amodem send data.recv + ~/receiver $ amodem recv --plot >data.rx ``` - -The following figures are be plotted: - -1. Prefix symbol: https://www.dropbox.com/s/lrk2ghastf7rbue/figure_1.png -1. Training symbols: https://www.dropbox.com/s/3jnmdjgd3zavcod/figure_2.png -1. Actual data symbols (full 64-QAM): https://www.dropbox.com/s/z0ca6tfvf8b8y8k/figure_3.png