cec-ctl

List CEC devices

$ cec-ctl --list-devices

$ sudo cec-ctl [[-m|--monitor]]

$ cec-ctl [[-S|--show-topology]]

cec-ctl [options]
cec-ctl -d device [command] [options]

-d device, --device device
    Specify the CEC device node to operate on (e.g., /dev/cec0).

-s, --status
    Display a brief status overview of the CEC adapter.

-S, --settings
    Show all current settings and capabilities of the CEC adapter.

--info
    Provide detailed information about the CEC adapter, including its driver and capabilities.

--query
    Query the capabilities supported by the CEC adapter hardware.

-v, --verbose
    Enable verbose output, providing more detailed logs of operations and CEC messages.

--monitor
    Continuously monitor and display all incoming and outgoing CEC messages.

--phys-addr [addr]
    Get the current physical address, or set it if an address is provided (e.g., 1.0.0.0).

--log-addr [addr_list]
    Get the current logical addresses, or set them using a comma-separated list of hex values (e.g., 4,8).

--power addr state
    Send a power command to a specific logical address. state can be on, off, toggle, or status.

--ping addr
    Send a ping message to a logical address to check if the device is responsive.

--send-msg msg
    Send a raw CEC message, provided as a hexadecimal string (e.g., 40:04 for power off from TV).

--playback, --recorder, --tuner, --processor, --tv, --audio-system
    Convenience options to set the device type for logical address assignment.

--osd-name [name]
    Get or set the On Screen Display (OSD) name of the device.

--menu-language [lang]
    Get or set the menu language using a 3-letter ISO 639-2/B code (e.g., eng for English).

--cec-version [version]
    Get or set the supported CEC version (e.g., 1.3a, 1.4, 2.0).

cec-ctl is a powerful command-line utility for interacting with and controlling Consumer Electronics Control (CEC) compatible devices connected via HDMI. It allows users to query CEC device capabilities, set adapter properties like logical and physical addresses, and send various CEC commands such as power on/off, input switching, and menu navigation to other connected devices within a home theater setup. This tool is particularly useful for automating interactions with TVs, AV receivers, and other HDMI-connected equipment from a Linux system. It typically operates on specific CEC device nodes, commonly found as /dev/cecX.

Using cec-ctl requires a CEC-enabled HDMI adapter or integrated hardware (e.g., on a Raspberry Pi).
Proper permissions on the /dev/cecX device nodes are necessary for non-root users.
Behavior and command support can vary significantly depending on the CEC hardware and the specific HDMI devices connected.
Not all CEC commands are universally supported by all manufacturers or device types.

Most cec-ctl commands require the -d or --device option to explicitly specify which CEC adapter to interact with. These adapters are typically enumerated as /dev/cec0, /dev/cec1, and so on. While some systems with a single CEC device might implicitly select it, it is best practice to always specify the device for clarity and robustness.

CEC communication relies on two types of addresses: the physical address, which reflects the HDMI port topology and hierarchy, and the logical address, a 4-bit address assigned dynamically to each CEC device type (e.g., TV, Playback Device, Audio System) to identify its function on the network. Understanding these addressing schemes is crucial for effectively targeting commands to specific devices.

cec-ctl is part of the v4l-utils project, a collection of utilities for Video4Linux devices. Its development tracks the evolution of CEC support within the Linux kernel, especially as CEC has become more prevalent in embedded systems like the Raspberry Pi. It provides a standardized command-line interface for interacting with CEC device nodes, abstracting the underlying hardware specifics.

v4l2-ctl(1), cec-compliance(1), udevadm(8)