A simple tool to send messages and commands into FreakWAN over Bluetooth low energy. It's tested under Linux, MacOS and Windows.
The best way to install freakble is using pipx:
$ pipx install freakble
For the GUI you can optionally install themes using:
$ pipx install 'freakble[themes]'
When using pip it's suggested to work inside a virtualenv.
$ python -m pip install freakble
freakble uses Poetry as dependency management and packaging tool, you need to install it first.
- Clone this repository.
- From the root of the repository run:
$ poetry build
- Install using pipx or pip (it's better to use pipx):
$ pipx install dist/freakble-0.1.0-py3-none-any.whl
Usage: freakble [OPTIONS] COMMAND [ARGS]... A simple tool to send messages into FreakWAN. Options: --adapter TEXT ble adapter [default: (hci0)] --help Show this message and exit. Commands: gui Start freakble GUI. repl Start a REPL with the device. scan Scan to find BLE devices. send Send one or more words over BLE to a specific device. version Return freakble version.
send command is used to send a message to the board. You need to know the
address of the device.
You can specify the address of a device using the
--device flag or the
The complete usage is:
Usage: freakble send [OPTIONS] [WORDS]... Send one or more words over BLE to a specific device. Options: --loop send forever the message --device TEXT ble device address [required] --sleep-time FLOAT sleep between messages sent with --loop [default: (1 sec)] --timeout FLOAT Bluetooth LE connection timeout [default: (10 secs)] --help Show this message and exit.
$ freakble send --device AA:AA:AA:AA:AA:AA Hello, there!
where you have to substitute
AA:AA:AA:AA:AA:AA with your device's address.
--loop flag will make freakble to send continuosly the message until
CTRL + C is pressed. The resend interval is defaults to 1 sec and can be
$ freakble send --device AA:AA:AA:AA:AA:AA --loop FREAKNET
You can use
FREAKBLE_DEVICE environment variables to set the device address,
and to not have to provide it in each commands that need a device address.
For example, using
send, if one of your device is called
you can do:
$ export FREAKBLE_DEVICE=$(freakble scan | grep FW_vuzasu | cut -d' ' -f1) $ freakble send "La violenza è l'ultimo rifugio degli incapaci. - Isaac Asimov"
FreakWAN supports commands starting with
! character (see the list on
$ freakble send '!bat' battery 99%, 4.20 volts
If you don't know what to say, you can always tempt the fates! :)
freakble send "$(fortune)"
Please note that this command handle also disconnection from Bluetooth LE so it runs in a few seconds.
scan command is used to discover Bluetooth LE devices.
Usage: freakble scan [OPTIONS] Scan to find BLE devices. Options: --scan-time FLOAT scan duration [default: (5 secs)] --help Show this message and exit.
$ freakble scan AB:AB:AB:AB:AB:AB (rssi:-52) FW_timatu AF:AF:AF:AF:AF:AF (rssi:-57) FW_vuzasu
repl command connects to the specified device and stats an interactive
shell with it.
The complete usage is:
Usage: freakble repl [OPTIONS] Start a REPL with the device. Options: --device TEXT ble device address [required] --timeout FLOAT Bluetooth LE connection timeout [default: (10 secs)] --help Show this message and exit.
$ export FREAKBLE_DEVICE=$(freakble scan | grep FW | cut -d' ' -f1) freakble 0.3.0a0 on linux Connecting to AB:AB:AB:AB:AB:AB... Φ]
Φ] is the freakble prompt.
You can then talk to the device remembering that commands start with
the text you write if it's not a command is sent as a message in the network.
For example, the following text is sent as a message in the network:
Φ] Hello there! Φ]
Instead commands make you able to get info or configure your FreakWAN node:
Φ] !help Commands: !automsg !pw !sp !cr !bw !freq !preset !ls !font !last !addkey !delkey !keys !usekey !nokey Φ] !bat battery volts: 4.2
TAB key or
! will show the autocompletion menu.
To exit from the interactive shell use
CTRL + D or
CTRL + C
gui command starts a GUI of freakble. If you don't set the device address
it will start with the following scan interface:
after choosing a device you can click to the connect button to get a graphical REPL:
freakble is licensed under BSD-3-Clause license.