Package: pycallblock
pycallblockIntroductionRequirementsInstallationUsageBlock modesExtended functionalityNotesGlossaryIntroductionThis project started in July 2020 after I finally decided
to do something about those daily spam calls.
I foundjcblock,
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.RequirementsHardwareYou need a computer and a USB modem. I use a Raspberry Pi Zero.
In theory it should work with anyATmodem,
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 oflsusbfor two modems that I have:0572:1340 Conexant Systems (Rockwell), Inc. USB Modem
0572:1340 Conexant Systems (Rockwell), Inc.They both look likethis.
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 installpyserialwhich comes withpyserial-portsandpyserial-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.0SoftwareLinux 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 thedialoutgroup
by doingsudo usermod -a -G dialout youruserand then logging out and in again.Installationpip install pycallblockUsagepycallblock 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: 120When you run pycallblock for the first time, it will create apycallblockdirectory in the user's home.
Inside, the database for logging the calls will be created
along with theplayandrecdirectories.
The recordings will go inrec, and inplayyou 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 atimezonewith--timezone.
On Windows you might need thetzdatapackage.Recording WAV filesThe audio must be unsigned PCM, mono, 8bit, at 8000Hz.
I useAudacityto record the WAV files.
In the bottom left corner set theProject Rateto 8000Hz,
and record your audio.
When exporting, chooseOther uncompressed filesthenWAV (Microsoft)andUnsigned 8-bit PCMand set the output channels to 1.
Then you can put the file inplayand test it to see if it plays correctly.It's also possible to use Audacity to convert an existing file by going toTracks -> Resample..., choosing 8000Hz and exporting as described above.Run as a serviceSee theexample file.
You can add the--syslogargument to the command and then dojournalctl -t pycallblockorjournalctl -u pycallblockto see the logs.
Do not use both--syslogand--stderrin this case.Block modesDefault behaviourInstantly 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 machineThe modem will act as a fax machine and play theCED tone.Play an audio filePlay a WAV file and hang up.TransmitSend audio until the timeout is reached or the caller hangs up.
If you want to play an audio file after picking up, use the-aoption.
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 likeIVR.
Not the most interesting mode for blocking calls, but it might have its use cases.RecordRecord 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.DuplexRecord + 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 theplaydirectory will be played after the specified amount of seconds
of silence has been reached.
The recording will contain the audio that is sent.Extended functionalityThe 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.CallbacksThe main way is by making your own subclass ofCallblockand overriding the callbacks.frompycallblockimportCallblockclassMyCallblock(Callblock):asyncdefring_callback(self,event):# awaited in the modem's event loop# Choose what happens when the phone ringsasyncdefcall_callback(self,call):# awaited in the modem's event loop# Choose what happens when you receive a callasyncdefmesg_callback(self,event):# awaited in the modem's event loop# Choose what happens when you receive a MESG eventasyncdefdtmf_callback(self,dtmf):# runs as a task# Choose what happens when you receive a DTMF during a callasyncdefsilence_callback(self):# runs as a task# Choose what happens when silence has been detectedIn case you want to reuse the same CLI and options, two functions are available:frompycallblockimportcli,options_from_argsfrompycallblock.modemimportModemargs=cli()options=options_from_args(args)asyncwithModem("/dev/ttyACM0")asmodem:mycallblock=MyCallblock(modem,...,options=options)Also, you can make callsfrompycallblock.modemimportModem,ModeasyncwithModem("/dev/ttyACM0")asmodem:wav="outgoing.wav"# Record to a fileawaitmodem.set_mode(Mode.VOICE)awaitmodem.send("AT+VSM=1")awaitmodem.start_voice_call("5055034455",wav=wav,max_duration=30)awaitmodem.voice_end()awaitmodem.hang_up()NotesHere are some notes in no particular order.there is always one ring before the caller ID is sentyour phone might have a setting to disable the first ringsometimes the phone still rings a few times after the call is blockeddepending on your hardware, the recordings may contain annoying background noisesthe 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 rebootssometimes the modem won't send BUSY after the caller hangs up,
in that case the call will last as long as the timeoutfor silence detection, as soon as there is noise the timer is resetin the modes where TX is active,
you'll always see oneReceived DSC: Transmit Buffer Underrunin the logseach call toModem.send_audio_fileputs 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 playedCallblock.startinstalls a signal handler forSIGINTandSIGTERM.
When one of these signals is received,
the pycallblock instance will be marked as not runningif a call is in progress when the program is exiting,
the call will terminate as soon as possiblethe modem's green LED turns on while a call is in progressthe+VSDcommand for silence detection exists but does nothing,
so I implemented a very basic silence detection on my ownI mostly usedthis reference manualthe country codes (unused for now) come fromthis oneGlossaryDCE:Data circuit-terminating equipmentDLE: Data link escapeDSC: DLE shielded code.DTE: Data terminal equipmentDTMF:Dual-tone multi-frequencyPVF: Portable voice formatRMD: Raw modem dataRX: ReceiveTX: Transmit