remoshockSource Code
Before you start working on the source code, please refer to the Setup Guide.
Get the source code
remoshock is open source. You can find the source code at https://github.com/remoshock/remoshock
To checkout the project and run the cli tool:
git clone git@github.com:remoshock/remoshock cd remoshock/src/ ./remoshockcli
🔀 Concepts
Commands and Actions
A command consists of the number of the targeted receiver, the action to perform (e. g. VIBRATE), the power level in percent and the duration in milliseconds. The main actions are BEEP, VIBRATE and SHOCK.
For condition training, there is a special action called BEEPSHOCK. It will play a beep sound, wait one second and follow up with a shock of the specified power level and duration.
Some receiver types will shut down after a period of inactivity with neither movement nor commands. The action KEEPAWAKE will be sent to those receivers periodically. The KEEPAWAKE commands are only sent, if they are required by the configured receiver type. Furthermore, they are only sent, if remoshockserver or remoshockrnd are running. If you are using remoshockcli, you will have to deal with sleep mode yourself.
Program Structure
The central class is Remoshock. It receives commands from the classes on the left hand side. Based on the configuration file $HOME/.config/remoshock.ini. It sets up a list of receivers, to which it forwards commands.
There is one class for each receiver type, which will generate the appropriate message based on the command details. In those classes the device specific logic is implemented. So if you plan to add support for an additional receiver, here is the place to look for examples. There is a document with information on how to analyze a remote protocol.
Receiver classes use an implementation of the SdrSender class to actually transmit the message. At this time, there are two implementation: One uses the command line tool provided by Universal Radio Hacker. The other one calls directly into the URH program code in order to prevent a 1 second delay.
One day, there should be a SdrSender implementation which uses the small hackrf_tramsfer cli instead of URH. Further more, it is possible to write an implementation for a cheap 433MHz transmitter boards instead of a software defined radio. But this will only work with receivers operating on 433MHz using OOK.
🧭 Directory Structure
| Package | Description |
|---|---|
| src | root directory of the source tree, contains the command line tool entry points. |
| remoshock | remoshock package with the implementation of the entry points |
| core | remoshock.py manages everything: It initializes the software and dispatches commands to the appropriate receiver. config.py implements the configuration wizard used when remoshock is started for the very first time. |
| receiver | receiver.py specifies the interface which is implemented by specialized classes for various receivers (shock collars brands) |
| scheduler | a scheduler which will invoke specified commands at a specified time in the future |
| sdr | access to the software defined radio hardware. The default implementation urhcli.py invokes the command line interface of Universal Radio Hacker. urhinternal.py is a hack that invokes internals of URH in order to prevent a 1s delay in the HackRF implementation. |
| util | utility classes e. g. logging and power management |
| web | HTML and JavaScript used by the web application |
| test | automated unit tests |
🔍 Quality Assurance
The following commands are executed automatically on Github. But you can invoke them locally to test your changes before creating a pull request:cd src flake8 --ignore E501,E303,W503 python3 -m unittest