SiUtil.py - Python wrapper for Silicon Labs MCU Programming Interface

All the functions of the Silicon Labs MCU Programming Interface (SiUtil.dll) are exposed via a Python class.

Requirements

• 32 bit Python
• Silicon Labs IDE (For SiUtil.dll and USBHID.dll)
• Silicon Labs ToolStick or Silicon Labs Debug Adapter

Usage Example

Connect to a USB debugger and print device and debugger information.

from siutil import SiUtil, SiUtilError

try:
    # Initialize the wrapper
    s = SiUtil()
    print(f"SiUtil DLL Version: {s.get_dll_version()}")

    # Find available USB debug adapters
    num_adapters = s.usb_debug_devices()
    if num_adapters == 0:
        print("No USB debug adapters found.")
    else:
        print(f"Found {num_adapters} USB adapter(s).")
        # Get serial number of the first adapter
        serial_number = s.get_usb_device_sn(0)
        print(f"Connecting to adapter with S/N: {serial_number}")

        # Connect to the device using C2 protocol
        s.connect_usb(serial_number, ec_protocol=1)
        
        if s.connected():
            print(f"-> Successfully connected to: {s.get_device_name()}")
            print(f"-> USB Adapter Firmware Version: {s.get_usb_firmware_version()}")
            s.disconnect_usb()
            print("-> Disconnected.")

except SiUtilError as e:
    print(f"An error occurred: {e}")

Function Reference

🔌 Connection

Function	Parameters	Return	Note
connect()	com_port=1, disable_dialogs=1, ec_protocol=0, baud_index=0	HRESULT	Connect to debugger using COM serial (ec_protocol: 0 for JTAG, 1 for C2)
connect_usb()	serial_num, ec_protocol=0, power_target=0, disable_dialogs=1	HRESULT	Connect to debugger using USB adapter (ec_protocol: 0 for JTAG, 1 for C2)
disconnect()	com_port=1	HRESULT	Disconnect from serial debugger
disconnect_usb()	(none)	HRESULT	Disconnect from USB debugger
connected()	(none)	bool	Check connection status

Note:
ec_protocol: 0 for JTAG, 1 for C2
baud_index: 0 for default baud rate

📝 Programming

Function	Parameters	Return	Note
download()	file_path, device_erase=0, disable_dialogs=1, download_scratch=0, bank_select=-1, lock_flash=0, persist_flash=1	HRESULT	Flash binary to device
download_cs()	file_path, device_erase=0, disable_dialogs=1, download_scratch=0, bank_select=-1, lock_flash=0, persist_flash=1	(HRESULT, checksum)	Flash binary to device and return checksum
verify_flash_download()	file_path, disable_dialogs=1, bank_select=-1	HRESULT	Check if flash matches binary
flash_erase()	com_port=1, disable_dialogs=1, ec_protocol=0	HRESULT	Mass erase using serial debugger
flash_erase_usb()	serial_num, disable_dialogs=1, ec_protocol=0	HRESULT	Mass erase using USB debugger

Note:
bank_select: -1 for non-banked, 0-3 for specific bank

💾 Memory - Read

Function	Parameters	Return	Memory Type
get_code_memory()	start_address, length	bytes	FLASH 0x0000-0x7FFF
get_ram_memory()	start_address, length	bytes	Internal RAM (DATA)
get_xram_memory()	start_address, length	bytes	Extended RAM (XDATA)
get_scratchpad_memory()	start_address, length	bytes	Scratch Pad

💾 Memory - Write

Function	Parameters	Return	Memory Type
set_code_memory()	start_address, data, disable_dialogs=1	HRESULT	FLASH 0x0000-0x7FFF
set_ram_memory()	start_address, data	HRESULT	Internal RAM (DATA)
set_xram_memory()	start_address, data	HRESULT	Extended RAM (XDATA)
set_scratchpad_memory()	start_address, data, disable_dialogs=1	HRESULT	Scratch Pad

📊 Device information

Function	Parameters	Return	Note
get_device_name()	(none)	str	Part number (e.g. "C8051F120-GM")
i_support_banking()	(none)	int	Number of FLASH banks

⚙️ Target commands

Function	Parameters	Return	Note
set_target_halt()	(none)	HRESULT	Halt CPU (breakpoint)
set_target_go()	(none)	HRESULT	Resume execution
target_reset()	(none)	HRESULT	Target warm reset

🔌 Adapter helpers

Function	Parameters	Return	Note
set_adapter()	b_adapter (1=USB, 2=SERIAL)	HRESULT	Set adapter type
usb_debug_devices()	(none)	int	Number of USB adapters found
get_usb_device_sn()	index	str	Serial number of USB adapter
get_sa_firmware_version()	(none)	int	Firmware version of serial adapter
get_usb_firmware_version()	(none)	int	Firmware version of USB adapter

🔧 Utility

Function	Parameters	Return	Note
get_dll_version()	(none)	str	DLL version (eg. "4.81.00")
get_error_msg()	hr_value	str	Get error message for given HRESULT value
set_app_name()	name (str)	(none)	App name for DLL logging