Usage

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

Built-in jobs:

Name	Args	Purpose
help		Print all callable jobs
stats	-a, -aa	Show specs of jobs such as memory, priority, loop status, instance count and error state. With no flag, it prints user jobs. -a prints user and base jobs. -aa prints all jobs, including core jobs.
echo	<text>	Reprint anything after echo (may not exceed MAX_JOB_ARGS_LEN_BYTE on the firmware side)
logp		If JES_LOG_LEN is left unmodified or set greater than 0, this command will list a log of JES_LOG_LEN runtime core interactions in chronological order with system time.
bench	<job>	Prints the roundtrip time of a job in ms, useful for benchmarking. Attention! It only reports logged timing data; it does not execute the job itself. For non-loop jobs, the job must have been called at least once before by the API or CLI. To set timing marks in a user loop, use __job_set_timing_begin() and __job_set_timing_end() from the backend job_driver.h!

These jobs are registered by jescore when the firmware CLI is enabled. Most are implemented in base_jobs.h / base_jobs.c; logp is provided by the core logging code and is only present when logging is enabled. 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.

Example Workflow with jescorecli

Discover the device

You flashed a project with jescore and registered the jobs job1 and job2. Let's assume that job1 is a loop that does not take arguments but prints a status every second and job2 is a worker that can take arguments. You can now run jescore -d in your terminal to discover compatible serial devices. When you run a command without -p, the CLI uses the first compatible port it detects. To view the discovery process, you can run jescore -d -v, which enables verbose output while scanning.

# example output for a connected STM32 Nucleo Board
$ jescore -d
ST LINK V3 (VID:PID=0483:374E | ttyACM0)

Check health of jescore

Now that you know your device's port, you can check if jescore is running properly. If you run jescore -p <myport> stats you will get

[jescore]:
name        handle      memory  prio    loop    instances   error
job1        <addr>      <mem>   <prio>  1       1           0
job2        0           <mem>   <prio>  0       0           0

This tells you that jescore is running and your application as well. As expected, job1 is a loop with an active instance. job2 is not a loop and will only receive an instance when activated. Both of these jobs will be printed in green; this means that they are yours, or more generally, user jobs.

Interact with your program

As stated, job1 is a loop that prints every second. How can we observe this output? To view everything the MCU prints, use jescore -l, which listens on the given or detected port and prints everything that it receives. You should see a new message from your controller every second. Use Ctrl+C to exit this stream.

You can also interact with job2 by giving it a command that you implemented. If you now write jescore job2 update, job2 will receive the argument update, which can be handled accordingly. If you defined a print statement in that job, you will then see it on screen as response, for example Updated job2!.

See the log of your program

jescore saves an amount of core interactions as runtime log that you can observe. Write jescore logp to print the current log. It will yield this output:

[jescore]:	
systime(ms)  type       name             instances error args
0            rgistr     logp             0         0
0            rgistr     clisrv           1         0
0            rgistr     echo             0         0
0            rgistr     help             0         0
0            rgistr     stats            0         0
0            rgistr     job1             0         0
0            rgistr     job2             0         0
1            launch     job1             1         0
2170         launch     job2             1         0     update
4150         launch     logp             0         0

In this log you can see the chronological order of job registrations and launches. In this case, job1 was launched at boot and job2 was launched after 2.1 seconds of runtime with the argument update. Finally, the log print was invoked after 4.1 seconds.

Benchmark your jobs

When you run a job that is not a loop, its execution time is logged. With this, you can now check how long it takes for your job to compute. For example, the job2 job can be benchmarked with jescore bench job2 after job2 has run at least once:

[jescore]:	
Roundtrip time (job2) = [ 6 ] ms