GitLocker: The Coding Marketplace

Description:

pycallblock 1.1.0

pycallblock

Introduction
Requirements
Installation
Usage
Block modes
Extended functionality
Notes
Glossary

Introduction
This project started in July 2020 after I finally decided
to do something about those daily spam calls.
I found jcblock,
which inspired me to make my own version of a call blocker.
So I bought a cheap modem and found a manual online.
I had no idea how all of this worked and it took some time to get used
to the modem and how to properly use it.
Seeing the caller ID show up for the first time in the terminal was very satisfying.
Then I found out that you can also use the modem to record the calls
and even send audio, and you basically get a phone controlled by software.
After a few years of successful blocking and some upgrades,
it's time for this project to be made public so that you can enjoy a silent
phone while the scammers are listening to the audio files you prepared for them.
Requirements
Hardware
You need a computer and a USB modem. I use a Raspberry Pi Zero.
In theory it should work with any
AT modem,
but I have not tested anything else than the Conexant based ones I have,
so I cannot guarantee that different models will work.
The modem must support caller ID, and voice mode if you want to use the voice features.
Unfortunately you can't really be sure of the modem's capabilities before you plug it in.
Only hardware modems are supported, this is not compatible with softmodems.
Here are the results of lsusb for two modems that I have:
0572:1340 Conexant Systems (Rockwell), Inc. USB Modem
0572:1340 Conexant Systems (Rockwell), Inc.

They both look like this.
It used to be easy to find them for pretty cheap on sites
like eBay and AliExpress but it seems like
that's not the case anymore, unfortunately.
If you have a wireless phone I guess you can use a one port modem.
If your phone is wired you'll need a modem with two ports.
Once you plug it in, the modem should show up as something like /dev/ttyACM0
(this the default device in pycallblock).
Installing pycallblock will install
pyserial
which comes with
pyserial-ports
and
pyserial-miniterm.
You can use this first command to find serial ports
and the second one to test your device.
Here's the output in my case:
$ pyserial-ports -v
/dev/ttyACM0
desc: USB Modem
hwid: USB VID:PID=0572:1340 SER=12345678 LOCATION=1-1:1.0

Software
Linux and Python 3.9+.
I did not test it on Windows, but if you can interface with the modem
just like you can do on Linux, and if the code is compatible,
there should be no reason for it not to work.
On Linux you'll probably have to add your user to the dialout group
by doing sudo usermod -a -G dialout youruser and then logging out and in again.
Installation
pip install pycallblock

Usage
pycallblock comes with a CLI:
optional arguments:
-h, --help show this help message and exit
-V, --version print version
--device DEV the device to use. Default: /dev/ttyACM0
--logfile FILE enable logging to the specified file
--syslog [ADDRESS] enable logging to syslog. Default: /dev/log
-p, --block-private block private numbers. Default: false
-l, --stderr log to stderr
-s SEC, --silence SEC seconds of silence before triggering the callback. Only for duplex. Must be an int or a float > 0. Default: disabled
-v, --verbose increase verbosity
-a FILE, --audio-file FILE WAV file for -m, -d and -t modes
--timezone TIMEZONE IANA timezone for the file names. Default: UTC
-b CSV, --blacklist CSV CSV file with the contacts that will be blocked
-w CSV, --whitelist CSV CSV file with the contacts that will be allowed

Block actions:
Choose what happens when a call is blocked. If nothing is specified, default to instant hangup.

-f, --fax act as a fax machine
-m, --message play a message specified with -a
-r [SEC], --record [SEC] record the call for SEC seconds. Default: 120
-d [SEC], --duplex [SEC] duplex for SEC seconds. Default: 120
-t [SEC], --transmit [SEC] transmit for SEC seconds. Default: 120

When you run pycallblock for the first time, it will create a pycallblock
directory in the user's home.
Inside, the database for logging the calls will be created
along with the play and rec directories.
The recordings will go in rec, and in play you can put your WAV files
to be randomly sent in duplex mode.
This is also where you can put your CSV file that contains blocked/allowed contacts.
The expected separator for the CSV file is the comma.
If you don't have a name for a contact, you must still put a comma after the number.
If you want to have a comma in the name, use double quotes around the name.
Example:
01234,
56789,Ben
5055034455,"Look, there's a comma"

If your block/allow list is empty, every call will be allowed/blocked respectively.
The recordings will be named according to the following format:
%Y-%m-%d %H-%M-%S%z NUMBER. The default timezone is UTC.
If you want your files to be named according to your local time,
set a timezone
with --timezone.
On Windows you might need the tzdata package.
Recording WAV files
The audio must be unsigned PCM, mono, 8bit, at 8000Hz.
I use Audacity to record the WAV files.
In the bottom left corner set the Project Rate to 8000Hz,
and record your audio.
When exporting, choose Other uncompressed files then WAV (Microsoft)
and Unsigned 8-bit PCM and set the output channels to 1.
Then you can put the file in play and test it to see if it plays correctly.
It's also possible to use Audacity to convert an existing file by going to
Tracks -> Resample..., choosing 8000Hz and exporting as described above.
Run as a service
See the example file.
You can add the --syslog argument to the command and then do
journalctl -t pycallblock or journalctl -u pycallblock to see the logs.
Do not use both --syslog and --stderr in this case.
Block modes
Default behaviour
Instantly hang up.
The caller's device might keep ringing,
but nothing should happen on your end.
Adding a delay before hanging up should help, in case that's what you want.
Fax machine
The modem will act as a fax machine and play the
CED tone.
Play an audio file
Play a WAV file and hang up.
Transmit
Send audio until the timeout is reached or the caller hangs up.
If you want to play an audio file after picking up, use the -a option.
In this mode, DTMFs are received.
This means that you could for example execute a certain action
(like playing a WAV file) when a specific button is pressed,
just like IVR.
Not the most interesting mode for blocking calls, but it might have its use cases.
Record
Record the call until the timeout is reached or the caller hangs up.
DTMFs are received, but because there's no transmit,
you can't send any audio back.
Duplex
Record + transmit. Recording alone can already give entertaining results,
but sometimes if there's no sound after the robot picks up, it will drop the call.
Like with transmit, you can set an audio file to be played at pick up.
If you enable silence detection with -s, a random file from the
play directory will be played after the specified amount of seconds
of silence has been reached.
The recording will contain the audio that is sent.
Extended functionality
The default functionality should already be enough for most.
But you can also build on top of pycallblock to make your own call blocker.
If you choose to do this, you'll have to write your own code to run the program.
It's only a few lines that you can find at the bottom of
__init__.py.
Callbacks
The main way is by making your own subclass of Callblock
and overriding the callbacks.
from pycallblock import Callblock

class MyCallblock(Callblock):

async def ring_callback(self, event): # awaited in the modem's event loop
# Choose what happens when the phone rings

async def call_callback(self, call): # awaited in the modem's event loop
# Choose what happens when you receive a call

async def mesg_callback(self, event): # awaited in the modem's event loop
# Choose what happens when you receive a MESG event

async def dtmf_callback(self, dtmf): # runs as a task
# Choose what happens when you receive a DTMF during a call

async def silence_callback(self): # runs as a task
# Choose what happens when silence has been detected

In case you want to reuse the same CLI and options, two functions are available:
from pycallblock import cli, options_from_args
from pycallblock.modem import Modem

args = cli()
options = options_from_args(args)
async with Modem("/dev/ttyACM0") as modem:
mycallblock = MyCallblock(modem, ..., options=options)

Also, you can make calls
from pycallblock.modem import Modem, Mode

async with Modem("/dev/ttyACM0") as modem:
wav = "outgoing.wav" # Record to a file
await modem.set_mode(Mode.VOICE)
await modem.send("AT+VSM=1")
await modem.start_voice_call("5055034455", wav=wav, max_duration=30)
await modem.voice_end()
await modem.hang_up()

Notes
Here are some notes in no particular order.

there is always one ring before the caller ID is sent
your phone might have a setting to disable the first ring
sometimes the phone still rings a few times after the call is blocked
depending on your hardware, the recordings may contain annoying background noises
the modem may report "fake" DSCs (this is a limitation of the way the modem works)
I've had instances where the modem becomes unresponsive and I have to restart the Pi,
or the Pi also crashes and reboots
sometimes the modem won't send BUSY after the caller hangs up,
in that case the call will last as long as the timeout
for silence detection, as soon as there is noise the timer is reset
in the modes where TX is active,
you'll always see one Received DSC: Transmit Buffer Underrun in the logs
each call to Modem.send_audio_file puts the audio in a queue.
Each file is played one by one.
If the queue is not empty when the call is ending,
the remaining files in the queue won't be played
Callblock.start installs a signal handler for SIGINT and SIGTERM.
When one of these signals is received,
the pycallblock instance will be marked as not running
if a call is in progress when the program is exiting,
the call will terminate as soon as possible
the modem's green LED turns on while a call is in progress
the +VSD command for silence detection exists but does nothing,
so I implemented a very basic silence detection on my own
I mostly used this reference manual
the country codes (unused for now) come from this one

Glossary

DCE: Data circuit-terminating equipment
DLE: Data link escape
DSC: DLE shielded code.
DTE: Data terminal equipment
DTMF: Dual-tone multi-frequency
PVF: Portable voice format
RMD: Raw modem data
RX: Receive
TX: Transmit