Introduction

charachorder.py is a wrapper around CharaChorder's Serial API. It provides functions for all of the commands available in the Serial API. It is a convenient way to kick-start your Python application that works on CharaChorder devices!

Lightweight wrapper with strict typing
Built with subclassing and customised usage in mind
Simple abstractions allow you to focus on logic-building

License

The charachorder.py source and documentation are released under the MIT License.

Installation

There are multiple ways to install the charachorder.py library. Choose any one of the methods below that best suit your needs.

From PyPI

You can use pip to install the package from PyPI

# Linux/macOS
python3 -m pip install -U charachorder.py

# Windows
py -3 -m pip install -U charachorder.py

From source

You can build from source by cloning the repository and installing it using pip:

git clone https://github.com/CharaChorder/charachorder.py
cd charachorder.py
python3 -m pip install -U .

Using nix shell

Running nix shell github:CharaChorder/charachorder.py will spawn a shell with Python 3.11 and this package installed. This has the caveat of not being able to change the Python version being used. To solve for this, use the package derivation itself (given below).

Using shell.nix or flake.nix

Simply copy this derivation into your project and call it using python3Packages.callPackage ./charachorder.nix { }. If you don't know where to paste this, then this installation method is probably not for you.

{ buildPythonPackage, fetchFromGitHub, lib, pythonOlder, inquirer, pyserial }:

buildPythonPackage {
  pname = "charachorder.py";
  version = "0.5.2";
  format = "setuptools";

  disabled = pythonOlder "3.9";

  src = fetchFromGitHub {
    owner = "CharaChorder";
    repo = "charachorder.py";
    rev = "v${version}";
    hash = ""; # FIXME: Fill the hash here. Hint: Run this once and you will get the hash in the error
  };

  nativeBuildInputs = [ inquirer pyserial ];

  meta = {
    description = "A wrapper for CharaChorder's Serial API written in Python";
    downloadPage = "https://pypi.org/project/charachorder.py/#files";
    homepage = "https://github.com/CharaChorder/charachorder.py";
    license = lib.licenses.mit;
    maintainers = with lib.maintainers; [ getpsyched ];
  };
}

Quickstart

This page gives a brief introduction to the library assuming you have already installed it.

Minimal

For most use cases, you'll likely want to use the existing classes and their methods as provided in the library. To get started, simply import the CharaChorder class that represents any CharaChorder device.

from charachorder import CharaChorder

for device in CharaChorder.list_devices():
    print(device)

The list_devices method finds and returns the list of CC devices connected to your system. Note that it will, in most cases, return a subclass of CharaChorder, such as CharaChorderOne, CharaChorderLite, etc.

You can also list out specific CC devices:

from charachorder import CharaChorderLite

for device in CharaChorderLite.list_devices():
    print(device)

The list_devices method here will ignore any other CC device and will only try to find CCL devices.

Sending serial commands

All of the serial API commands are wrapped in methods of each CC class. Although, to send these commands, you must first connect to the serial port where the device is connected. Don't worry, the library provides 2 ways you can do this:

Method 1: - recommended

Using the with context manager, you don't need to worry about opening or closing the serial connection, it will do it automatically for you!

with device:
    # run commands here

Method 2:

Some use cases may require the serial connection to be used over a long period and frequently toggling it may become expensive. For that, you can manually manage the connection using the open and close methods.

device.open()
# run commands here
device.close()

Some examples are:

with device:
    # ID
    id: str = device.get_id()

    # VERSION
    version: str = device.get_version()

    # CML C0
    total_chords: int = device.get_chordmap_count()

A full list of methods is given in the reference guide (TODO).

charachorder.py documentation