jescore is a CLI native system, even though it is run on an embedded system. The CLI is on a client machine to which the controller is connected to, for example during development. During that time, It makes a lot of sense to interact with the controller over the very same machine that flashed it. Using this CLI is not a must; but it helps during development, for cross-platform unit testing and stable UI design. The paradigm is simple:

Register a job under a name and that name will be CLI callable, executing the function when evoked.

Extra arguments can of course be specified. These will be passed as-is to the job that will be executed and can be retrieved with jes_job_get_args().The delimiting character for job name and subsequent arguments is a whitespace.

Usually, your device has many physical or virtual serial connections. Yet somehow jescore recognizes your MCU like the ESP32. This is because the jescore-cli looks for registered vendor IDs and product IDs, identifiers for USB connections. jescore-cli does not actually know all MCUs, just the ones manually added to KNOWN_HOSTS in common.py. This list will be expanded as jescore grows.

The CLI requires a client machine (your PC or any machine that can run either python or a serial terminal emulator) and your MCU to be connected via the serial line. For most dev-boards, this is integrated into the normal USB connection used for power and flashing. If you have an off-the-shelf dev-board connected to your PC right now, there is a 90% chance that your hardware setup is ready for jescore.

The repository of jescore contains a subfolder jescore_cli, which houses python wrappers for serial communications. It can be installed as a python package.

Create a virtual python environment and install the CLI there.

python -m venv .venv
source .venv/bin/activate
pip install jescore/jescore_cli

You can now call jescore -h for help on the client side or jescore help for help on the MCU side if it runs a program that contains jes_init().

The python side of the CLI only has 4 arguments:

I use jescore for many projects and therefore want it globally. This way I can just run jescore from any terminal on my machine. You can achieve the same with pipx or a forced pip installation (not recommended). Install pipx and run pipx install jescore/jescore_cli. The CLI can now be accessed from any terminal. The CLI only depends on one installable package, which is pyserial. For this reason, I deem it to be ok to install it globally.

In the end, all the jescore CLI uses is a UART TX and RX line. This means that you can omit the python based CLI if you know what you are doing. For example, you can use the terminal emulator PuTTY to open the serial stream directly. jescore will still respond if you configure your terminal emulator to send and receive messages and do such in a manner that it behaves like a local terminal (e.g., messages are sent on enter, not after every keystroke). You could even hook up another MCU to control the other. All it takes is the UART line and some string parsing. The python wrapper is evoked by writing jescore <cmd>, which does not apply to the version with the direct UART connection. Here, you just send <cmd>, which is the name of a job you registered in the MCU code. To reiterate, this is two different pairs of shoes: a direct connection is a "stream", meaning that new prints from the MCU will show up in real time on the emulator. This is not the same as the python wrapper calling for a response, which of course will only happen if a command is sent first. Support for a python based open UART stream is planned.

Expected command shapes:
jescore <job_name> [args] (with jescore-cli) <job_name> [args] (with direct UART comms)

These jobs can be found in base_jobs.h. They are part of jescore and always present. Calling stats -aa lists even more jobs, but these are part of the core and you should not interact with them. Refer to the backend documentation.

If you installed jescore-cli, you can of course treat it like every other desktop program. This also means that you can create an alias for it if it suits your needs. On Linux, append alias mycoolproject='jescore' to the bottom of your ~/.bashrc file. You can now call your registered jobs with mycoolproject stats and receive stats. Having complete name rewrite to suit user's needs is planned but not implemented.