peanut

README

Process control and execution utility overview

peanut is the process execution and control utility for OCClib-based O² processes. Its purpose is to be a debugging and development aid for OCC-based and FairMQ O² devices.

In aliBuild it is part of the coconut package.

peanut can connect to a running OCClib-based or FairMQ process, query its status, drive its state machine and push runtime configuration data.

peanut runs in two modes depending on whether a command is passed:

• TUI mode — interactive terminal UI (launched when no command is given)
• CLI mode — non-interactive, scriptable (launched when a command is given)

---

TUI mode

peanut [flags]

Flag	Default	Description
-addr	""	gRPC address host:port; if empty, falls back to OCC_CONTROL_PORT env var (direct mode only)
-mode	direct	direct, fmq, or fmq-step (see below)

Modes

direct — OCC protobuf (default)

Connects to an OCClib-based process using the standard OCC protobuf codec. The state machine operates on OCC states: STANDBY, CONFIGURED, RUNNING, ERROR.

OCC_CONTROL_PORT=47100 peanut
# or
peanut -addr localhost:47100 -mode direct

Control buttons: CONFIGURE, RESET, START, STOP, RECOVER, EXIT

fmq — FairMQ JSON codec with automatic multi-step sequencing

Connects to a FairMQ device using the JSON codec. Each OCC-level button press automatically drives the full underlying FairMQ state machine sequence. The state is displayed as an OCC-mapped state (STANDBY, CONFIGURED, RUNNING…).

peanut -addr localhost:47100 -mode fmq

Control buttons: CONFIGURE, RESET, START, STOP, RECOVER, EXIT

Sequences driven automatically:

Button	FairMQ steps
CONFIGURE	INIT DEVICE → COMPLETE INIT → BIND → CONNECT → INIT TASK
RESET	RESET TASK → RESET DEVICE
START	RUN
STOP	STOP
RECOVER	RESET DEVICE (from ERROR)
EXIT	RESET (if needed) → END

fmq-step — FairMQ JSON codec with granular per-step control

Connects to a FairMQ device using the JSON codec. Exposes each individual FairMQ state machine step as a separate button. The state is displayed as the raw FairMQ state.

peanut -addr localhost:47100 -mode fmq-step

Key	Button	Transition
1	INIT DEVICE	IDLE → INITIALIZING DEVICE
2	COMPLETE INIT	INITIALIZING DEVICE → INITIALIZED
3	BIND	INITIALIZED → BOUND
4	CONNECT	BOUND → DEVICE READY
5	INIT TASK	DEVICE READY → READY
6	RUN	READY → RUNNING
7	STOP	RUNNING → READY
8	RESET TASK	READY → DEVICE READY
9	RESET DEVICE	→ IDLE
0	END	IDLE → EXITING

Common TUI controls (all modes)

Key	Action
n	Reconnect — re-establish the gRPC connection to the controlled process. Use this when the process has been restarted after a crash or deliberate termination.
l	Load configuration — open a file dialog to read a YAML or JSON configuration file. The path field supports tab-completion. Once loaded, the right panel shows NOT PUSHED until the next CONFIGURE transition, then PUSHED.
q	Quit — disconnect and exit without sending any transitions.

Connection monitoring

While connected, peanut polls GetState every 2 seconds in a background goroutine. If the process stops responding, the state display shows UNREACHABLE and an error modal appears. After restarting the controlled process, press n to reconnect.

Transition buttons are dimmed and disabled until a connection is successfully established.

Connection error states

State	Meaning
CONNECTING	Connection attempt in progress
UNREACHABLE	No process is listening on the given address, or the connection was lost after a successful connect
WRONG MODE	A process is running but speaks a different protocol — check the -mode flag

If WRONG MODE is shown, peanut will suggest the correct mode in the error modal.

Runtime configuration files

Configuration files are YAML or JSON, with arbitrarily nested structure. peanut flattens them to dot-notation key=value pairs before pushing. Integer map keys and integer values are both handled correctly.

Example (channel configuration):

chans:
  data:
    numSockets: 1
    0:
      address: ipc://@o2ipc-example
      method: bind
      type: push
      transport: shmem
      sndBufSize: 1000
      rcvBufSize: 1000
      sndKernelSize: 0
      rcvKernelSize: 0
      rateLogging: 0

This flattens to entries like chans.data.0.address=ipc://@o2ipc-example.

---

CLI mode

peanut [flags] <command> [args]

Flag	Default	Description
-addr	localhost:47100	gRPC address host:port
-mode	fmq	fmq (JSON codec) or direct (protobuf)
-timeout	30s	timeout for unary gRPC calls
-config	""	path to YAML/JSON file; flattened key=value pairs are sent as arguments. Inline key=val arguments take precedence.

Commands

get-state

Print the current FSM state.

peanut -addr localhost:47100 get-state

transition <fromState> <toState> [key=val ...]

High-level state transition. In fmq mode drives the full multi-step FairMQ sequence automatically.

# FairMQ: drive full configure sequence
peanut -addr localhost:47100 -mode fmq transition STANDBY CONFIGURED \
  chans.data.0.address=ipc://@o2ipc-example

# FairMQ: with config file
peanut -addr localhost:47100 -mode fmq -config stfsender-configure-args.yaml \
  transition STANDBY CONFIGURED

# Direct OCC
peanut -addr localhost:47100 -mode direct transition STANDBY CONFIGURED

FairMQ sequences driven automatically:

From → To	Steps
STANDBY → CONFIGURED	INIT DEVICE, COMPLETE INIT, BIND, CONNECT, INIT TASK
CONFIGURED → RUNNING	RUN
RUNNING → CONFIGURED	STOP
CONFIGURED → STANDBY	RESET TASK, RESET DEVICE

direct-step <srcState> <event> [key=val ...]

Low-level: send a single raw OCC gRPC Transition call (protobuf codec).

peanut -addr localhost:47100 -mode direct direct-step STANDBY CONFIGURE key=val

Events: CONFIGURE, RESET, START, STOP, RECOVER, EXIT

fmq-step <srcFMQState> <fmqEvent> [key=val ...]

Low-level: send a single raw FairMQ gRPC Transition call (JSON codec). State/event names that contain spaces must be quoted.

peanut -addr localhost:47100 fmq-step IDLE "INIT DEVICE" chans.x.0.address=ipc://@foo
peanut -addr localhost:47100 fmq-step READY RUN

state-stream

Subscribe to StateStream and print state updates until interrupted (Ctrl-C).

peanut -addr localhost:47100 state-stream

event-stream

Subscribe to EventStream and print events until interrupted (Ctrl-C).

peanut -addr localhost:47100 event-stream

---

Limitations

• The GO_ERROR transition cannot be triggered from peanut, as it is only triggered from user code inside the controlled process.
• Quit / q disconnects without sending any transition. A future instance of peanut can reattach to the same process and continue.

Documentation

Overview

Package peanut implements a process execution and control utility for OCClib-based O² processes, providing debugging and development support.

Index

• func Run(opts Options) (err error)
• func RunCLI(args []string) error
• type Options

Functions

func Run

func Run(opts Options) (err error)

func RunCLI

func RunCLI(args []string) error

RunCLI runs peanut in non-interactive CLI mode. args should be os.Args[1:].

Types

type Options

type Options struct {
	Addr string // host:port; if empty, falls back to OCC_CONTROL_PORT env var (occ mode only)
	Mode string // "direct" (default), "fmq", or "fmq-step"
}

Options configures the peanut TUI.