advanced_usb_control.h File Reference

Detailed Description

Advanced USB Control System

This system allows one to communicate with the ESP at runtime and issue a series of commands from userspace applications using HID API. This can be concurrent to using the interface as any type of HID device, mouse, keyboard etc.

This is a convenient way of writing to flash, IRAM, etc. and testing out code without needing to reflash the whole chip.

Commands are in the form:

[0xaa (or report ID = 0xaa)] [1-byte COMMAND] [4-byte parameter] [Data or parameters ...]

Note

The first byte is the report ID. In some systems this is separate. In others it is the first byte of the message. You will need to consult examples to determine which way this is.

Note

Windows and Linux behave differently. In Windows, you always must transfer exactly REPORT_SIZE+1 bytes (With first byte being the report ID (0xAA). Linux allows variations.

Note

On Windows and Linux you can transfer arbitrary lengths of data for FEATURE_GET commands.

IF YOU KNOW HOW TO SEND ARBITRARY DATA LENGTHS FOR FEATURE_SET ON WINDOWS, PLEASE CONTACT ME (cnlohr)

The commands that are supported are defined in ausb_cmd_t.

Go to the source code of this file.

Macros
#define	SCRATCH_IMMEDIATE_DWORDS   64
	The number of 32 bit variables in the RAM scratch space.

Enumerations
enum	ausb_cmd_t {   AUSB_CMD_REBOOT = 0x03 , AUSB_CMD_WRITE_RAM = 0x04 , AUSB_CMD_READ_RAM = 0x05 , AUSB_CMD_EXEC_RAM = 0x06 ,   AUSB_CMD_SWITCH_MODE = 0x07 , AUSB_CMD_ALLOC_SCRATCH = 0x08 , ACMD_CMD_MEMSET = 0x09 , ACMD_CMD_GET_VER = 0x0a ,   AUSB_CMD_FLASH_ERASE = 0x10 , AUSB_CMD_FLASH_WRITE = 0x11 , AUSB_CMD_FLASH_READ = 0x12 }

Functions
int	handle_advanced_usb_control_get (uint8_t *data, int reqLen)
	Accept a "get" feature report command from a USB host and write back whatever is needed to send back.
int	handle_advanced_usb_terminal_get (uint8_t *data, int reqLen)
	USB request to get text in buffer.
void	handle_advanced_usb_control_set (const uint8_t *data, int datalen)
	Accept a "send" feature report command from a USB host and interpret it. executing whatever needs to be executed.
int	advanced_usb_write_log_printf (const char *fmt, va_list args)
	vaprintf stand-in for USB logging.
int	uprintf (const char *fmt,...)
	vaprintf stand-in for USB logging.

Macro Definition Documentation

SCRATCH_IMMEDIATE_DWORDS

#define SCRATCH_IMMEDIATE_DWORDS   64

The number of 32 bit variables in the RAM scratch space.

Enumeration Type Documentation

ausb_cmd_t

enum ausb_cmd_t

The command types that may be sent over USB

Note

parameters are 4-bytes, LSB first byte.

Enumerator
AUSB_CMD_REBOOT	AUSB_CMD_REBOOT: 0x03 Parameter 1: Zero: Just reboot. Nonzero: Reboot into bootloader.
AUSB_CMD_WRITE_RAM	AUSB_CMD_WRITE_RAM: 0x04 Parameter 0: Address to start writing to. Parameter 1 [2-bytes]: Length of data to write Data to write...
AUSB_CMD_READ_RAM	AUSB_CMD_READ_RAM: 0x05 Parameter 0: Address to start reading from. NOTE: Must use "get report" to read data
AUSB_CMD_EXEC_RAM	AUSB_CMD_EXEC_RAM: 0x06 Parameter 0: Address to "call"
AUSB_CMD_SWITCH_MODE	AUSB_CMD_SWITCH_MODE: 0x07 Parameter 0: Pointer to Swadge mode (will change) If 0, will go to main mode without reboot.
AUSB_CMD_ALLOC_SCRATCH	AUSB_CMD_ALLOC_SCRATCH: 0x08 Parameter 0: Size of scrach requested. If -1, simply report. If 0, deallocate scratch. NOTE: Address and size of scratch will be available to "get reports" as two 4-byte parameters.
ACMD_CMD_MEMSET	ACMD_CMD_MEMSET: 0x09 Parameter 0: Start of memory to memset Parameter 1: Byte to write.
ACMD_CMD_GET_VER	ACMD_CMD_GET_VER: 0x0a Writes a 16-byte version identifier in the scratch, which can be read. Format TBD.
AUSB_CMD_FLASH_ERASE	AUSB_CMD_FLASH_ERASE: 0x10 Parameter 0: Start address of flash to erase. Parameter 1 [4 bytes]: Size of flash to erase. NOTE: For flash erase commands, you MUST use sector-aligned values!
AUSB_CMD_FLASH_WRITE	AUSB_CMD_FLASH_WRITE: 0x11 Parameter 0: Start address of flash to write. Parameter 1 [2 bytes]: Length of data to write Payload: Data to write.
AUSB_CMD_FLASH_READ	AUSB_CMD_FLASH_READ: 0x12 Parameter 0: Start address of flash to read. Parameter 1 [2 bytes]: Quantity of flash to read (Cannot exceed SCRATCH_IMMEDIATE_DWORDS) NOTE: The data is written to a scratch buffer

Function Documentation

handle_advanced_usb_control_get()

int handle_advanced_usb_control_get	(	uint8_t *	data,
		int	reqLen )

Accept a "get" feature report command from a USB host and write back whatever is needed to send back.

Parameters

reqLen	Number of bytes host is requesting from us.
data	Pointer to a feature get request for the command set.

Returns

Number of bytes that will be returned.

handle_advanced_usb_terminal_get()

int handle_advanced_usb_terminal_get	(	uint8_t *	data,
		int	reqLen )

USB request to get text in buffer.

Parameters

reqLen	The number of bytes the host is requesting from us.
data	The data that we will write back into

Returns

size Number of bytes to be returned to the host.

handle_advanced_usb_control_set()

void handle_advanced_usb_control_set	(	const uint8_t *	data,
		int	datalen )

Accept a "send" feature report command from a USB host and interpret it. executing whatever needs to be executed.

Parameters

datalen	Total length of the buffer (command ID included)
data	Pointer to full command

advanced_usb_write_log_printf()

int advanced_usb_write_log_printf	(	const char *	fmt,
		va_list	args )

vaprintf stand-in for USB logging.

Parameters

fmt	vaprintf format
args	vaprintf args

Returns

size Number of characters that were written.

uprintf()

int uprintf	(	const char *	fmt,
			... )

vaprintf stand-in for USB logging.

Parameters

fmt	vaprintf format
...	vaprintf args

Returns

size Number of characters that were written.