1
0
Fork 0
Go to file
Daniele Tricoli 50c90e0a59 Bump version to 0.5.3 2023-02-23 20:57:24 +01:00
.github/workflows Enable pre-commit on GitHub 2023-02-13 03:22:11 +01:00
extras Add a section about gui command 2023-02-23 17:54:54 +01:00
src/freakble Bump version to 0.5.3 2023-02-23 20:57:24 +01:00
tests Initial import 2023-02-09 23:56:22 +01:00
.editorconfig Configure black and isort and editors supporting editorconfig 2023-02-10 00:10:17 +01:00
.flake8 Add flake8 config 2023-02-10 00:39:23 +01:00
.gitignore Initial import 2023-02-09 23:56:22 +01:00
.pre-commit-config.yaml Enable pre-commit on GitHub 2023-02-13 03:22:11 +01:00
CHANGELOG.md Update CHANGELOG 2023-02-23 20:57:04 +01:00
LICENSE Initial import 2023-02-09 23:56:22 +01:00
README.md Fix themes installation command 2023-02-23 20:56:01 +01:00
justfile Change version in pyproject.toml only at the beginning 2023-02-23 20:48:28 +01:00
poetry.lock Make really theming optional 2023-02-23 20:48:04 +01:00
pyproject.toml Bump version to 0.5.3 2023-02-23 20:57:24 +01:00

README.md

freakble

A simple tool to send messages and commands into FreakWAN over Bluetooth low energy. It's tested under Linux but it should work also on other platforms.

Installation

Using pipx

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]'

Using pip

$ python -m pip install freakble

From source

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

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:
  deep-scan  Scan to find services of a specific device.
  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

The send command is used to send a message to the board. You need to know the address of the 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)]
  --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

A photo of a LYLIGO TTGO LoRa v2 1.6 showing the text: you> FREAKNET in multiple lines.

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 FreakWAN_vuzasu you can do:

$ export FREAKBLE_DEVICE=$(freakble scan | grep FreakWAN_vuzasu | cut -d' ' -f1)
$ freakble send "La violenza è l'ultimo rifugio degli incapaci. - Isaac Asimov"

scan

The scan command is used to discover BLE devices.

Usage: freakble scan [OPTIONS]

  Scan to find BLE devices.

Options:
  --scan-time FLOAT    scan duration  [default: (5 secs)]
  --service-uuid TEXT  service UUID used to filter  [default: (None)]
  --help               Show this message and exit.

For example:

$ freakble scan
AB:AB:AB:AB:AB:AB (RSSI=-52): FreakWAN_timatu
AF:AF:AF:AF:AF:AF (RSSI=-57): FreakWAN_vuzasu

Please note that the address are invented.

deep-scan

The deep-scan command is used to find services of a specific device.

Usage: freakble deep-scan [OPTIONS]

  Scan to find services of a specific device.

Options:
  --device TEXT      ble device address  [required]
  --scan-time FLOAT  scan duration  [default: (5 secs)]
  --help             Show this message and exit.

repl

The repl command connects to the specified device and stats an interactive shell with it.

$ export FREAKBLE_DEVICE=$(freakble scan | grep FreakWAN | 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 !sp !cr !bw !freq
Φ] !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

gui

The gui command starts a GUI of freakble. If you don't set the device address it will start with the following scan interface:

A screenshot of the scan inferface of the gui.

after choosing a device you can click to the connect button to get a graphical REPL:

A screenshot of the graphical REPL of freakble.

License

freakble is licensed under BSD-3-Clause license.