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.

Then:

1. Clone this repository.
2. From the root of the repository run:

   $ poetry build

3. 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.

The 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 environment variable FREAKBLE_DEVICE.

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.

For example:

$ 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.

The --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 changed using --sleep-time.

$ 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 FW_vuzasu 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 FreakWAN README):

$ 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.

The 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.

For example:

$ freakble scan
AB:AB:AB:AB:AB:AB (rssi:-52) FW_timatu
AF:AF:AF:AF:AF:AF (rssi:-57) FW_vuzasu

The 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.

For example:

$ 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 ! and 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

Pressing TAB key or ! will show the autocompletion menu.

To exit from the interactive shell use CTRL + D or CTRL + C

The 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.