Somewhat large-ish change:

  - Allow "led presets" (which specify 1 or more pin, colour settings) to
    be added to the user's config, and then apply them with the `apply_led_preset`
    command
  - Add the `list_devices` command, which enumerates serial devices and determines
    which ones are Busy Tag (or something compatible :-)
  - Change tool behaviour so that the config file is only updated when the `--device`
    flag is used
  - Bump the PyPI version to v0.1.1

Author: acoster

.idea/busytag_tool.iml

@@ -1,4 +1,6 @@
 # busytag_tool
+[![PyPI version](https://img.shields.io/pypi/v/busytag)](https://pypi.org/project/busytag/)
+![License](https://img.shields.io/pypi/l/busytag)
 
 Python library and CLI to interact with [Busy Tag](https://www.busy-tag.com/) devices using
 the [USB CDC interface]( https://luxafor.helpscoutdocs.com/article/47-busy-tag-usb-cdc-command-reference-guide).
@@ -11,14 +13,18 @@ $ pip install busytag
 
 ## CLI usage
 
-The first time the tool is used, you should pass the device path through
-the flag `--device=/dev/whatever`. This will be saved in `~/.busytag.toml`
-and will be used in subsequent runs where `--device` is not passed.
+The first time the tool is used, you should pass the device path through the flag `--device=/dev/whatever`. This
+will be saved in `~/.busytag.toml` and will be used in later runs where `--device` is not passed. If you don't the port
+for your device, you can run `busytag-tool list_devices` to find it.
 
 ```shell
-$ busytag-tool 
+$ busytag-tool
+
+	USAGE: busytag-tool [flags] <command> [<args>]
+
 Available commands:
   help: Prints this message
+  list_devices: Lists available devices
   info: Displays device information
   list_pictures: Lists pictures in device
   list_files: Lists files in device
@@ -28,15 +34,43 @@ Available commands:
   get <filename>: Copies <filename> from the device to the working directory
   rm <filename>: Deletes <filename>
   set_led_solid_color <6 hex RGB colour>: Sets the LEDs colour
+  apply_led_preset <preset name>: Sets the LEDs colour according to a preset
   get_brightness: Gets current display brightness
   set_brightness <brightness>: Sets current display brightness (int between 1 and 100, inclusive
+
+$ busytag-tool set_picture coding.png
+```
+
+### Config
+
+A config file with the device port is created at `~/.busytag.toml`. You can also add "led preset" entries there,
+which can then be used with the `apply_led_preset` to change the device's LED colours. For example, here are two
+entries, one that applies the same colour to all LEDs, and another that alternates colours:
+
+```toml
+[[led_presets.red]]
+pins = 127
+color = 'FF0000'
+
+[[led_presets.rb]]
+pins = 85
+color = 'FF0000'
+
+[[led_presets.rb]]
+pins = 42
+color = '0000FF'
 ```
 
+The BusyTag device has seven LEDs (with the first one, 0, at the bottom left of the device), identified in this tool by
+powers of two. The `pins` entry in the config is the sum of which pins we want to apply the colour (so `127` applies
+to all, while `85` applies to pins 0, 2, 4 and 6).
+
 ## API usage
 
 ```python
-from busytag import Device
+from busytag import Device, LedConfig, LedPin
 
 bt = Device('/dev/fooBar')
 bt.set_active_picture('coding.gif')
+bt.set_led_solid_color(LedConfig(LedPin.ALL, 'FF0000'))
 ```

README.md

@@ -1,18 +1,16 @@
 [project]
 name = "busytag"
-version = "0.1.0"
+version = "0.1.1"
 dynamic = ["dependencies"]
 authors = [{ name = "Alex Coster", email = "[email protected]" }]
 description = "A library and CLI tool to control Busy Tag devices."
 readme = "README.md"
 requires-python = ">=3.11"
 license = "MIT"
 license-files = ["LICENSE"]
-classifiers = [
-    "Development Status :: 2 - Pre-Alpha",
+classifiers = ["Development Status :: 2 - Pre-Alpha",
     "Environment :: Console",
-    "Operating System :: OS Independent"
-]
+    "Operating System :: OS Independent"]
 
 [project.scripts]
 busytag-tool = "busytag.tool:run_main"

pyproject.toml

@@ -1,31 +1,53 @@
 # SPDX-License-Identifier: MIT
 
-import tomlkit
 import os.path
+from typing import Optional, Sequence
+
+import tomlkit
 
 from .types import *
 
-from typing import Optional, Sequence
 
 class ToolConfig(object):
     def __init__(self, path: Optional[str] = None):
         self.device = None
         self.path = path
+        self.led_presets = {}
         if path is not None:
             self.path = os.path.expanduser(path)
             if os.path.exists(self.path):
                 self.__load_from_file()
 
-
     def write_to_file(self):
         assert self.path is not None
         conf = {}
+
         if self.device is not None:
             conf['device'] = self.device
+
+        conf['led_presets'] = {}
+        for name, settings in self.led_presets.items():
+            preset = []
+            for setting in settings:
+                preset.append({'pins': int(setting.pins), 'color': setting.color})
+            conf['led_presets'][name] = preset
+
         with open(self.path, "w") as fp:
             tomlkit.dump(conf, fp)
 
+    def get_led_preset(self, name: str) -> Sequence[LedConfig]:
+        if name not in self.led_presets:
+            raise ValueError(f'LED preset {name} not found')
+        return self.led_presets[name][::]
+
     def __load_from_file(self):
         with open(self.path, 'rb') as fp:
             conf = tomlkit.load(fp)
-            self.device = conf['device']
+            if 'device' in conf:
+                self.device = conf['device']
+
+            if 'led_presets' in conf:
+                for key, entry in conf['led_presets'].items():
+                    self.led_presets[key] = []
+                    for pattern in entry:
+                        self.led_presets[key].append(LedConfig(LedPin(int(pattern['pins'])), pattern['color']))

src/busytag/config.py

@@ -1,10 +1,10 @@
 #!/usr/bin/env python
 # SPDX-License-Identifier: MIT
-
-from absl import app, flags
-
 from os.path import basename, expanduser
-from typing import List
+from typing import List, Optional
+
+import serial.tools.list_ports
+from absl import app, flags, logging
 
 from .config import ToolConfig
 from .device import Device
@@ -15,30 +15,61 @@
 flags.DEFINE_string('device', None, 'Busy Tag\'s serial port.')
 flags.DEFINE_integer('baudrate', 115200, 'Connection baudrate.')
 
+
 def format_size(size: int) -> str:
     if size < 1_000:
         return f'{size} B'
     if size < 500_000:
-        return f'{size/1_000:.2f} kB'
-    return f'{size/1_000_000:.2f} MB'
-
-
-def main(argv: List[str]) -> None:
+        return f'{size / 1_000:.2f} kB'
+    return f'{size / 1_000_000:.2f} MB'
+
+
+def list_devices(baudrate: int) -> List[str]:
+    devices = []
+    ports = serial.tools.list_ports.comports()
+    logging.debug(f'Probing {len(ports)} serial devices...')
+
+    for port in ports:
+        try:
+            logging.debug(f'Trying to connect to {port.device}')
+            with serial.Serial(port.device, baudrate=baudrate, timeout=1.0) as conn:
+                logging.debug(f'Connected to {port.device}')
+                conn.write(b'AT+GDN\r\n')
+                while True:
+                    response = conn.readline()
+                    logging.debug(f'Read from device: {response}')
+                    if response.startswith(b'+evn'):
+                        continue
+                    if response.startswith(b'+DN:busytag-'):
+                        devices.append(port.device)
+                    break
+        except Exception:
+            pass
+
+    return devices
+
+
+def main(argv: List[str]) -> Optional[int]:
     config = ToolConfig(FLAGS.config_file)
     if FLAGS.device is not None:
         config.device = FLAGS.device
-    if config.device is None:
-        raise Exception('Device must be specified')
+    config.write_to_file()
 
-    bt:Device = None
+    bt: Optional[Device] = None
 
     # Remove argv[0]
-    argv.pop(0)
+    exec_name = argv.pop(0)
     command = 'help'
     if len(argv) > 0:
         command = argv.pop(0)
-        bt = Device(config.device, baudrate=FLAGS.baudrate)
 
+        # Don't bother connecting for commands that don't need a device connection.
+        if command not in ('list_devices', 'help'):
+            if config.device is None:
+                print('A device must be specified using the `--device` flag or be set in the config file!')
+                print(f'You can run `{exec_name} list_devices` to find the available devices.')
+                return 1
+            bt = Device(config.device, baudrate=FLAGS.baudrate)
 
     match command:
         case 'info':
@@ -49,6 +80,15 @@ def main(argv: List[str]) -> None:
             print(f'Storage capacity: {format_size(bt.capacity)}')
             print(f'Free storage:     {format_size(bt.get_free_storage())}')
 
+        case 'list_devices':
+            devices = list_devices(FLAGS.baudrate)
+            if len(devices) == 0:
+                print('No devices found')
+            else:
+                print('Available devices:')
+                for device in devices:
+                    print(f'  {device}')
+
         case 'list_pictures':
             print('Pictures in device:')
             for picture in bt.list_pictures():
@@ -91,6 +131,15 @@ def main(argv: List[str]) -> None:
             led_config = LedConfig(LedPin.ALL, argv.pop(0).upper())
             bt.set_led_solid_color(led_config)
 
+        case 'apply_led_preset':
+            assert len(argv) >= 1
+            preset_name = argv.pop(0)
+
+            # Clear all LEDs first
+            bt.set_led_solid_color(LedConfig(LedPin.ALL, '000000'))
+            for e in config.led_presets.get(preset_name):
+                bt.set_led_solid_color(e)
+
         case 'get_brightness':
             print(f'Brightness: {bt.get_display_brightness()}')
 
@@ -101,8 +150,10 @@ def main(argv: List[str]) -> None:
             bt.set_display_brightness(brightness)
 
         case 'help':
+            print(f'\n\tUSAGE: {exec_name} [flags] <command> [<args>]\n')
             print('Available commands:')
             print('  help: Prints this message')
+            print('  list_devices: Lists available devices')
             print('  info: Displays device information')
             print('  list_pictures: Lists pictures in device')
             print('  list_files: Lists files in device')
@@ -112,16 +163,20 @@ def main(argv: List[str]) -> None:
             print('  get <filename>: Copies <filename> from the device to the working directory')
             print('  rm <filename>: Deletes <filename>')
             print('  set_led_solid_color <6 hex RGB colour>: Sets the LEDs colour')
+            print('  apply_led_preset <preset name>: Sets the LEDs colour according to a preset')
             print('  get_brightness: Gets current display brightness')
             print('  set_brightness <brightness>: Sets current display brightness (int between 1 and 100, inclusive')
+            print(f'\nFor flag documentation, run {exec_name} --help')
 
         case _:
             print(f'Unknown command `{command}`. Please use the `help` to list available commands')
+            return 1
+    return 0
 
-    config.write_to_file()
 
 def run_main():
     app.run(main)
 
+
 if __name__ == '__main__':
-    run_main()
+    run_main()