Overview

The elcap device subcommands provide functionality for interacting with physical devices in a variety of ways. This ranges from discovering what devices can be seen by your computer to locking down the flash on an MCU so it cannot be read out. Each of these commands have command line –options for executing the commands. These options are situationally required so they are not all needed for every command use case. This document will go over when each of the options for each command is required and how to use them. This information can also be gotten from running elcap with the --help option.

Device Discover

elcap device discover

Shows all connected programmers/devices over USB and IP.

Device Info

elcap device info

Read device information including the EUI64 (Extended Unique Identifier) from the connected device.

Options

--option	description	default
--usb	USB serial number of the JLink device	None
--ip	IP address of the JLink device	None
--alias	Alias for the JLink device	None
--target	Chip target - 'T32CM11C' or 'T32CZ20B'	None or chip from project directory
--interface	Programming interface	SWD
--speed	Programming speed	Detected from device or 4000
--help	Print help for this sub-command	None

NOTE: The --usb, --ip, and --alias options are mutually exclusive - only use one at a time to identify the device.

Device Erase

elcap device erase

Erase internal flash on a device. By default, this preserves the token space and only erases the application flash. Use the --all option to erase the entire flash including tokens.

Options

--option	description	default
--usb	USB serial number of the JLink device	None
--ip	IP address of the JLink device	None
--alias	Alias for the JLink device	None
--target	Chip target - 'T32CM11C' or 'T32CZ20B'	None or chip from project directory
--interface	Programming interface	SWD
--speed	Programming speed	Detected from device or 4000
--all	Erase entire flash (application and token space)	False
--help	Print help for this sub-command	None

NOTE: The --usb, --ip, and --alias options are mutually exclusive - only use one at a time to identify the device.

Erase Application Flash Only

elcap device erase

Erase Entire Flash (Including Tokens)

elcap device erase --all

Erase Specific Device

If no device identifier is provided, elcap will prompt you to select from available devices.

$ elcap device erase
Select a device:
1. my-devkit (USB, Serial: 123456789, COM: COM4)
Select device (default: 123456789):
Select a chip target: 1
1. T32CM11C
2. T32CZ20B
Select target (default: T32CM11C): 1
Chip erase completed successfully.

Using USB serial number:

elcap device erase --usb 123456789

Using IP address:

elcap device erase --ip 192.168.1.100

Using alias:

elcap device erase --alias my-devkit

Device Erase-Sector

elcap device erase-sector <start_addr> <stop_addr>

Erase a specified address range of flash memory. This allows for granular control over which sectors of flash are erased without affecting the entire chip.

Arguments

argument	description	required
start_addr	Flash start address	Yes
stop_addr	Flash stop address	Yes

Options

--option	description	default
--usb	USB serial number of the JLink device	None
--ip	IP address of the JLink device	None
--alias	Alias for the JLink device	None
--target	Chip target - 'T32CM11C' or 'T32CZ20B'	None or chip from project directory
--interface	Programming interface	SWD
--speed	Programming speed	Detected from device or 4000
--help	Print help for this sub-command	None

NOTE: The --usb, --ip, and --alias options are mutually exclusive - only use one at a time to identify the device.

Erase Specific Flash Range

elcap device erase-sector 0x00000000 0x0000FFFF

Erase Specific Device Flash Range

If no device identifier is provided, elcap will prompt you to select from available devices.

$ elcap device erase-sector 0x00000000 0x0000FFFF
Select a device:
1. my-devkit (USB, Serial: 123456789, COM: COM4)
Select device (default: 123456789):
Select a chip target: 1
1. T32CM11C
2. T32CZ20B
Select target (default: T32CM11C): 1
Sector erase completed successfully.

Using USB serial number:

elcap device erase-sector 0x00000000 0x0000FFFF --usb 123456789

Using IP address:

elcap device erase-sector 0x00000000 0x0000FFFF --ip 192.168.1.100

Using alias:

elcap device erase-sector 0x00000000 0x0000FFFF --alias my-devkit

Device Lock

elcap device lock

Enable flash readout protection on the target MCU to prevent unauthorized access to firmware. Device lock exists to protect the MCU's flash from being read out. Different chips have different requirements to enable this feature which means not all command line --options are required for every chip.

Options

--option	description	default
--usb	USB serial number of the JLink device	None
--ip	IP address of the JLink device	None
--alias	Alias for the JLink device	None
--target	Chip target - 'T32CM11C' or 'T32CZ20B'	None or chip from project directory
--interface	Programming interface	SWD
--speed	Programming speed	Detected from device or 4000
--port	Serial port (e.g., /dev/ttyUSB0, COM3)	None
--confirm	Auto-confirm device lock without interactive prompt	You will be prompted to confirm.
--help	Print help for this sub-command	None

NOTE: The --usb, --ip, and --alias options are mutually exclusive - only use one at a time to identify the device.

T32CM11C

WARNING: It is not possible to unlock this chip! Proceed with caution...

The T32CM11C uses permanent flash readout protection. Once locked, the device cannot be unlocked using elcap commands. See SDK Documentation for unlock options.

elcap device lock

Auto-confirm without interactive prompt:

elcap device lock --confirm

Lock specific device:

elcap device lock --usb 123456789
elcap device lock --ip 192.168.1.100
elcap device lock --alias my-devkit

T32CZ20B

The elcap device lock command disables the T32CZ20B's SWD interface preventing reading and writing flash. (See device unlock for temporarily unlocking / enabling debug and re-flashing.)

The lock operation will permanently write the Root and ADAC public keys into the T32CZ20B's OTP secure key storage.
The required keys for locking a T32CZ20B are the Root and ADAC public signing keys.
It's possible to use private keys instead of public keys because elcap can derive the public keys from the private if you wanted to store only private key files for instance.
The Root key must be the same Root key as used in the Z-Wave project.
The key files can be either .pem or .der format files.
The private keys may be password protected.
The lock operation is safe to run more than once but has no effect after the first run.
The T32CZ20B must be reset via asserting the nReset pin or by power-cycling for lock to take effect by the BootROM.

T32CZ20B Specific Lock Options

In addition to the device interface options, you must provide paths to either the public or private key files matching your Z-Wave project.

--option	Description
--root-private-key-path	Path to an ECDSA p-256 private key .der/.pem file.
--root-private-key-password	Optional password to the root private key file.
--root-public-key-path	Path to an ECDSA p-256 public key .der/.pem file.
--adac-private-key-path	Path to an ECDSA p-256 private key .der/.pem file.
--adac-private-key-password	Optional password to the ADAC private key file.
--adac-public-key-path	Path to an ECDSA p-256 public key .der/.pem file.

T32CZ20B Specific Lock Examples

Using public keys

elcap device lock --root-public-key-path "keys_directory/root_p256_public_key.pem" --adac-public-key-path "keys_directory/adac_p256_public_key.pem" --target T32CZ20B --usb <J-Link Serial>

Using private keys

elcap device lock --root-private-key-path "keys_directory/root_p256_private_key.pem" --adac-private-key-path "keys_directory/adac_p256_private_key.pem" --target T32CZ20B --usb <J-Link Serial>

Add --confirm to not be prompted for confirmation...

elcap device lock --root-public-key-path "keys_directory/root_p256_public_key.pem" --adac-public-key-path "keys_directory/adac_p256_public_key.pem" --target T32CZ20B --usb <J-Link Serial> --confirm

T32CZ20B Device Keys

Note: The ADAC private/public key files are not currently generated by our build system like the Root and other signing keys are.

It's possible to just copy any of the public/private key pairs from an example project to use as your ADAC key if you don't want to bother running OpenSSL directly.

The Root and ADAC private and public keys can be generated using openssl:

openssl ecparam -genkey -name prime256v1 -noout -out keys/private_key.pem

The Root and ADAC public key files can be generated from the private keys in either PEM or DER format:

openssl ec -in private_key.pem --outform PEM -pubout -out public_key.pem

openssl ec -in private_key.pem --outform DER -pubout -out public_key.der

Device Unlock

elcap device unlock

Device unlock is intended to disable the flash readout protection that is enabled using the elcap device lock command. Again, different chips have different interfaces so not all --options are required for all chips.

T32CM11C

Unlocking is not supported for this chip. See SDK Documentation for unlock options.

T32CZ20B

The elcap device unlock command temporarily enables the T32CZ20B's SWD interface allowing reading, writing, and erasing flash and full debugger functionality.

The command performs an Authenticated Debug Access Control (ADAC) challenge and response with the T32CZ20B's BootROM serial interface (UART0) connected to the J-Link's bridged serial/COM port.

T32CZ20B Specific Unlock Options

The only required option for unlocking a T32CZ20B is the ADAC public key file.

--option	Description
--adac-private-key-path	Path to an ECDSA p-256 private key .der/.pem file.
--adac-private-key-password	Optional password to the ADAC private key file.

T32CZ20B Specific Unlock Examples

elcap device unlock --adac-private-key-path "keys_directory/adac_p256_private_key.pem" --target T32CZ20B --usb <J-Link Serial>

See device lock for information about the keys.

Device TTY

elcap device tty

Connect to a device via serial terminal for logging and CLI access. This command opens an interactive serial terminal session for communicating with the device's UART interface. Press Ctrl+C to exit the terminal.

Options

--option	description	default
--port, -p	Serial port (e.g., /dev/ttyUSB0, COM3)	None
--baudrate, -b	Baud rate (common values: 115200, 230400)	115200
--databits, -d	Data bits (5, 6, 7, 8)	8
--stopbits, -s	Stop bits (1, 1.5, 2)	1
--parity	Parity (none, odd, even, mark, space)	none
--flow, -f	Flow control (none, xonxoff, rtscts)	none
--help	Print help for this sub-command	None

Connect to Device

Auto-select port (prompts if multiple ports available):

elcap device tty

Specify port:

elcap device tty --port /dev/ttyUSB0

elcap device tty --port COM3

Connect with Custom Serial Settings

Custom baud rate:

elcap device tty --port /dev/ttyUSB0 --baudrate 230400

Full configuration:

elcap device tty --port /dev/ttyUSB0 --baudrate 115200 --databits 8 --stopbits 1 --parity none --flow none

Using short option names:

elcap device tty -p /dev/ttyUSB0 -b 230400 -d 8 -s 1 -f none

NOTE: If no port is specified, elcap will list available serial ports and prompt you to select one. If only one port is available, it will be selected automatically.

Device Rename

elcap device rename

Assign or update a device alias/nickname. The alias is stored directly on the J-Link device so it will persist across different computers. This allows you to refer to devices by friendly names instead of serial numbers or IP addresses.

Options

--option	description	default
--usb	USB serial number of the JLink device	None
--ip	IP address of the JLink device	None
--alias	Existing alias to select the device	None
--name, -n	New alias to assign to the device	None
--unset	Remove alias/nickname from device (cannot be used with –name)	False
--help	Print help for this sub-command	None

NOTE: The --usb, --ip, and --alias options are mutually exclusive - only use one at a time to identify the device. The --name and --unset options are also mutually exclusive.

Rename Device

Auto-select device and prompt for alias:

elcap device rename

Rename specific device by USB serial:

elcap device rename --usb 123456789 --name my-devkit

Rename specific device by IP:

elcap device rename --ip 192.168.1.100 --name lab-device

Rename using existing alias:

elcap device rename --alias old-name --name new-name

Using short option:

elcap device rename --usb 123456789 -n my-devkit

Remove Alias

Remove alias from specific device:

elcap device rename --usb 123456789 --unset
elcap device rename --ip 192.168.1.100 --unset
elcap device rename --alias my-devkit --unset

NOTE: Aliases must not exceed 31 characters. If no device identifier is provided, elcap will prompt you to select from available devices.

Device Update Firmware

elcap device update-firmware

Check for new firmware available for a certain device through ElCap's managed dependencies. If a newer version is found, the firmware will update automatically.

Options

--option	description	default
--usb	USB serial number of the JLink device	None
--ip	IP address of the JLink device	None
--alias	Existing alias to select the device	None
--help	Print help for this sub-command	None

NOTE: The --usb, --ip, and --alias options are mutually exclusive - only use one at a time to identify the device.

Update Firmware

If no device identifier is provided, elcap will prompt you to select from available devices.

$ elcap device update-firmware
Select a device:
1. Trident IoT Device (USB, Serial: 900040683, COM: COM9)
2. CZ20-board1 (USB, Serial: 900040112, COM: COM8)
3. TestingRename3 (IP: 10.0.0.10)
Select device (default: 900040683): 2
Programmer firmware is up to date.
Firmware: J-Link OB-K22-Cortex-M compiled Jul  8 2025 10:14:58

Update specific device by USB serial:

elcap device update-firmware --usb 900040112

Update specific device by IP:

elcap device update-firmware --ip 10.0.0.10

Update using existing alias:

elcap device update-firmware --alias CZ20-board1

Device Recover

elcap device recover

During development, if a chip target's firmware (unintentionally) disables the debug SWD interface, your debugger device may no longer be able to connect to the chip target to flash and debug.

The elcap device recover command will attempt to recover chip target's SWD interface by erasing the chip target's flash using the BootROM serial interface (UART0) through the J-Link's bridged serial/COM port.

Requirements

The chip Target must be T32CZ20B.
The chip must not be locked.
The chip must be powered.
The chip's ground, VBat(Vdd), nReset, UART0 RX/TX lines must be connected properly to the J-Link.

Options

--option	Description	Default
--usb	USB serial number of the JLink device	None
--ip	IP address of the JLink device	None
--alias	Alias for the JLink device	None
--target	Chip target - 'T32CM11C' or 'T32CZ20B'	None or chip from project directory
--interface	Programming interface	SWD
--speed	Programming speed	Detected from device or 4000
--help	Print help for this sub-command	None

NOTE: The --usb, --ip, and --alias options are mutually exclusive - only use one at a time to identify the device.

ElCap Documentation