How to use HDMI-CEC on the Raspberry Pi

HDMI-CEC is a special protocol designed for the TV to communicate with another device over an HDMI cable. This protocol allows the TV to control another device while allowing that device to control the TV.

Most modern TVs have implemented support for this protocol, but it usually has to be enabled in the TV's settings. Searching for the TV model will help you know what this setting is called.

Using the HDMI-CEC protocol, you can use the Raspberry Pi to control the TV in a variety of ways, such as turning on and off, or changing the volume.

You can use the Raspberry Pi to control the TV in a variety of ways

Install the cec-client onto the Raspberry Pi

In this section, the article will show you the simple steps to install cec-client software on your Raspberry Pi. cec-client is a software package that will be used on the Raspberry Pi to control the device over the HDMI-CEC protocol.

Step 1. The first task is to update the package list on the Raspberry Pi as well as to upgrade the packages currently installed. Run the following two commands.

sudo apt update sudo apt upgrade

The first command will update the package list. The second command will upgrade the installed packages.

Step 2. The next step is to install the cec-utils package . This package contains the cec-client software that will be used later in this tutorial.

You can install this package onto your Raspberry Pi by running the following command.

sudo apt install cec-utils

Using the tools provided by this bundle, you can send commands using CEC over an HDMI cable connected to the Raspberry Pi.

Interact with TV over HDMI-CEC using the Raspberry Pi

In this section, the article will show you how to use different cec-client software to interact with other devices.

Throughout this section, you will notice that there are a few things you will do for each step.

The first is to use echo and | . Use these two to pass commands directly to the cec-client software without having to launch it.

Additionally, both the -s and -d options are also being used with the cec-client software.

The -s option tells the software that you will issue a single command. The software will launch, issue commands and then exit immediately.

Option -d 1 sets the debug level for the software. By setting it to 1 , the cec-client software will only display the error.

This setting significantly reduces the amount of text that will fill the console.

Scan HDMI-CEC device from Raspberry Pi

Step 1. The first thing you'll need to do is scan available devices that are advertising that they have CEC capabilities. Scan for HDMI-CEC-enabled devices by running the following command on the Raspberry Pi.

echo 'scan' | cec-client -s -d 1

Step 2. From this command, you will see a list of the devices that the Raspberry Pi currently has access to.

You need to identify the device you want to interact with. Typically the fields 'os string:' and 'vendor:' will help you identify the devices you want to interact with.

Once you have identified the correct device, write down the 'address:' or the device number.

opening a connection to the CEC adapter. requesting CEC bus information . CEC bus information =================== device #0: TV address: 0.0.0.0 active source: no vendor: Sony osd string: TV CEC version: 1.4 power status: standby language: eng device #1: Recorder 1 address: 1.0.0.0 active source: no vendor: Pulse Eight osd string: CECTester CEC version: 1.4 power status: on language: eng device #4: Playback 1 address: 3.0.0.0 active source: no vendor: Sony osd string: PlayStation 4 CEC version: 1.3a power status: standby language: ???

Please note that 'device # 1: Recorder 1' in this example is the Raspberry Pi's own CEC connection so you can safely bypass it.

Step 3. For example, if you want to control 'Sony TV' , you can see that the device number will be '0' and the device's address will be '0.0.0.0'.

Once you have a device number or device address, you can start sending commands to it.

Send 'on' command via HDMI-CEC

Using the cec-client to turn on the device is a relatively easy process.

echo 'on ' | cec-client -s d 1

As you can see above, all you need to do is send an on command followed by the device address or device number.

Example of turning on device via HDMI-CEC

For example, if you want to turn on a Sony TV whose address is '0.0.0.0', use the command shown below.

echo 'on 0.0.0.0' | cec-client -s -d 1

Sends the 'standby' command via HDMI-CEC

If you want to turn off the TV (put it on standby) using your Raspberry Pi, you can do this easily using HDMI-CEC as well.

echo 'standby ' | cec-client -s d 1

To put the TV in standby mode all you need to do is send the " standby " command , followed by the device's address or number.

Example of how to turn off a device via HDMI-CEC

Using this command is relatively simple. To put the Sony TV in standby mode all you need to do is send 'standby' followed by the device's address '0.0.0.0'.

echo 'standby 0.0.0.0 | cec-client -s -d 1

Get power status via HDMI-CEC

You can even use HDMI-CEC on the Raspberry Pi to retrieve a device's power state.

echo 'pow ' | cec-client -s d 1

Using the pow command, you can find out if the device you are connecting to is currently powered on or in standby mode. This command can be useful to decide if you need to turn the TV on or off, especially when managing the device remotely.

Example of receiving power status via HDMI-CEC

Like most HDMI-CEC commands, doing this is relatively easy. All you need to do is the pow reference, followed by the device address.

echo 'pow 0.0.0.0' | cec-client -s -d 1

If the device is in standby mode, you should see something like the one below appear in Terminal.

opening a connection to the CEC adapter. power status: standby

Retrieve additional CEC-Client commands

If you want to check if you can give other commands to the TV from the Raspberry Pi using HDMI-CEC, you can use the following command.

echo 'h' | cec-client -s -d 1

What this command does is retrieve the available commands that the cec-client software knows how to handle.

From this command you will get a list of commands, like the example shown below.

================================================================================ Available commands: [tx] {bytes} transfer bytes over the CEC line. [txn] {bytes} transfer bytes but don't wait for transmission ACK. [on] {address} power on the device with the given logical address. [standby] {address} put the device with the given address in standby mode. [la] {logical address} change the logical address of the CEC adapter. [p] {device} {port} change the HDMI port number of the CEC adapter. [pa] {physical address} change the physical address of the CEC adapter. [as] make the CEC adapter the active source. [is] mark the CEC adapter as inactive source. [osd] {addr} {string} set OSD message on the specified device. [ver] {addr} get the CEC version of the specified device. [ven] {addr} get the vendor ID of the specified device. [lang] {addr} get the menu language of the specified device. [pow] {addr} get the power status of the specified device. [name] {addr} get the OSD name of the specified device. [poll] {addr} poll the specified device. [lad] lists active devices on the bus [ad] {addr} checks whether the specified device is active. [at] {type} checks whether the specified device type is active. [sp] {addr} makes the specified physical address active. [spl] {addr} makes the specified logical address active. [volup] send a volume up command to the amp if present [voldown] send a volume down command to the amp if present [mute] send a mute/unmute command to the amp if present [self] show the list of addresses controlled by libCEC [scan] scan the CEC bus and display device info [mon] {1|0} enable or disable CEC bus monitoring. [log] {1 - 31} change the log level. see cectypes.h for values. [ping] send a ping command to the CEC adapter. [bl] to let the adapter enter the bootloader, to upgrade the flash rom. [r] reconnect to the CEC adapter. [h] or [help] show this help. [q] or [quit] to quit the CEC test client and switch off all connected CEC devices. ================================================================================

At this point, you have learned how to use the cec-client on your Raspberry Pi to control devices that support the HDMI-CEC protocol.

Good luck!

Samuel Daniel

Update 15 October 2020