Skip to content

Command Line Interface Guide

Jump to bottom
Guo-Rong edited this page Jul 26, 2026 · 11 revisions

Introduction

pico-cec now presents itself as a composite USB device to the host system:

  • Human Interface Device (HID)
    • for sending mapped key entries
  • Communications and CDC Control (CDC)
    • for a basic command line interface over serial

This guide covers the CDC behaviour of pico-cec and a basic CLI overview.

Serial Port Access

On a Linux system, pico-cec will typically appear as a hotplug USB tty device like /dev/ttyACM0. Access is via your favourite terminal client, for example screen, like so:

$ screen /dev/ttyACM0 115200

where 115200 is the baud rate (and usually not required).

Command Line Interface (CLI)

Overview

The CLI is a basic text input/output command line driven system. It features basic tab completion and history. Help is available via the help command. Similar to some network device configuration, changing parameters and saving changes are separate functions. This allows us to:

  • avoid unnecessary flash writes
  • eventually support ephemeral changes

Commands

debug {on|off}

Control debugging trace output:

  • eg. debug on
    • enable debug output
  • eg. debug off
    • disable debug output

query {edid}

Perform a system query:

  • eg. query edid
    • issue EDID request over DDC to probe physical address

send <addr> <opcode> [<operand>]*

Send a CEC opcode to the specified logical address:

  • eg. send 0 4
    • send CEC code 0x4 (Image View On) to address 0x0 (TV)
  • eg. send f 36
    • send CEC code 0x36 (Standby) to all devices 0xf (broadcast)
  • eg. send f 82 14 00
    • send CEC code 0x82 (Active Source) to all devices 0xf (broadcast) with address 0x1400 (1.4.0.0)

save

Commit any changes introduced via set to non-volatile storage. These changes will persist across reboots.

set (config {edid_delay_ms|logical_address|physical_address|osd_name} <value>)|(device_type {playback|recording})|(keymap {kodi|mister}|(custom <cec> <hid>)))

Change a configuration parameter:

  • config {edid_delay_ms|logical_address|physical_address|osd_name} <value>

    • edid_delay_ms - the delay in milliseconds during boot before issuing the EDID request over DDC
      • eg. set config edid_delay_ms 10000
        • delay for 10s before trying to auto-detect the physical address
        • useful to avoid interfering with HDMI source's EDID probe
      • default = 5000ms
    • logical_address - hardcode the logical CEC address
      • eg. set config logical_address 4
        • use with caution, logical address must match device type
        • avoid using if at all possible, can cause serious CEC addressing collisions
      • default = f (unregistered, auto-allocate)
    • physical_address - hardcode the physical CEC address
      • eg. set config physical_address 2200
        • prevent auto-EDID and hardcode pico-cec to address '2.2.0.0'
        • useful if EDID probing just won't work
      • default = 0000 (no hardcode, use auto-EDID)
    • osd_name - On Screen Display name
      • eg. set config osd_name bazzite
        • pico-cec identifies itself as bazzite
      • eg. set config osd_name "My Player"
        • pico-cec identifies as "My Player"
      • default = Pico-CEC
      • maximum 14 characters, printable ASCII only

  • device_type {playback|recording}

    • eg. set device_type recording
      • useful to avoid logical address collisions with other devices
      • try this before hardcoding the logical address
    • default = 4 (playback device)

  • keymap ({kodi|mister}(custom <cec> <hid>)) - set the keymap

    • eg. set keymap kodi
      • use the kodi keymap
    • eg. set keymap mister
      • use the MisTer keymap
    • eg. set keymap custom 71 3a
    • default = kodi

show {cec|config|keymap|(stats {cec|cpu|tasks})|version}

Display information.

  • cec
    • display runtime CEC information
    • eg. show cec
    • useful for determining EDID probe failure (physical address is 0x0000) and the hammer approach is desired (set config physical_address xxxx)
  • config
    • display current configuration parameters
    • eg. show config
  • keymap
    • display the current CEC command to key stroke mapping
  • stats {cec|cpu|tasks}
    • display basic stats
    • eg. show stats cec
      • display CEC frame counters
      • interesting and perhaps useful in future for debugging
    • eg. show stats cpu
      • display uptime and CPU usage for each task
      • uptime is interesting, CPU usage by task isn't (pico-cec idles a lot)
    • eg. show stats tasks
      • display task priority and stack usage
      • priority is hardcoded and largely uninteresting
      • stack (min) is the minimum stack free observed
        • if this gets close to 0 there is risk of a stack overflow
  • version
    • eg. show version
    • display the version

reboot [bootsel]

Reboot the system

  • eg. reboot
    • reboot the system for saved changes to take effect
  • eg. reboot bootsel
    • reboot into boot select mode
    • this is equivalent to holding 'boot + reset'
    • useful for development and avoiding touching the hardware

Clone this wiki locally