USB control interface
Controlling the board from the USB host
USB is the main control interface for the board and allows the host to configure and control the board.
A master-slave scheme is used where the USB host is the master and the board is the slave.
It’s to the master to initiate a control session by issuing a command to the board and await for a response.
For some commands the response is just and acknowledgement, for others the response has some data.
USB commands
The commands are 64 byte messages sent from the master to the slave.
The responses are also 64 byte messages.
Switch downstream ports
Switches the downstream ports on and off.
Both the Vbus lines and the data-lines are switched on and off.
Command message structure
| byte 0 |
byte 1 |
… |
byte 63 |
| action |
control |
don’t care |
don’t care |
Command message values
| action |
control byte |
Command |
| 0x01 |
0x01 |
Port 1 off |
| 0x02 |
0x02 |
Port 2 off |
| 0x03 |
0x03 |
Port 3 off |
| 0x0A |
0x0A |
All ports off |
| 0x11 |
0x11 |
Port 1 on |
| 0x12 |
0x12 |
Port 2 on |
| 0x13 |
0x13 |
Port 3 on |
| 0x1A |
0x1A |
All ports on |
Response message structure
| byte 0 |
byte 1 |
… |
byte 63 |
| status |
response |
don’t care |
don’t care |
Response message values
| status |
response |
Description |
| 0x01 |
0x01 |
Port 1 off |
| 0x01 |
0x02 |
Port 2 off |
| 0x01 |
0x03 |
Port 3 off |
| 0x01 |
0x0A |
All ports off |
| 0x01 |
0x11 |
Port 1 on |
| 0x01 |
0x12 |
Port 2 on |
| 0x01 |
0x13 |
Port 3 on |
| 0x01 |
0x1A |
All ports on |
Get port state
Ask the board for the switching state of a port.
Command message structure
| byte 0 |
byte 1 |
… |
byte 63 |
| action |
control |
don’t care |
don’t care |
Command message values
| action |
control |
Description |
| 0x21 |
0x21 |
Port 1 state |
| 0x22 |
0x22 |
Port 2 state |
| 0x23 |
0x23 |
Port 3 state |
Response message structure
| byte 0 |
byte 1 |
… |
byte 63 |
| status |
state |
don’t care |
don’t care |
Response message values
| status |
state |
Description |
| 0x01 |
0x01 |
Port 1 off |
| 0x01 |
0x02 |
Port 2 off |
| 0x01 |
0x03 |
Port 3 off |
| 0x01 |
0x11 |
Port 1 on |
| 0x01 |
0x12 |
Port 2 on |
| 0x01 |
0x13 |
Port 3 on |
Switch controllable 5V power port
Commands to switch on and off the 5V output power port.
Command message structure
| byte 0 |
byte 1 |
… |
byte 63 |
| action |
control |
don’t care |
don’t care |
Command message values
| action |
control |
Description |
| 0x04 |
0x04 |
Port off |
| 0x14 |
0x14 |
Port on |
| 0x24 |
0x24 |
Port state |
Response message structure
| byte 0 |
byte 1 |
… |
byte 63 |
| status |
state |
don’t care |
don’t care |
Response message values
| status |
state |
Description |
| 0x01 |
0x04 |
Port off |
| 0x01 |
0x14 |
Port on |
GPIO Read/Write
Commands to read an write from/to GPIO pins.
Command message structure
| byte 0 |
byte 1 |
byte 2 |
… |
byte 63 |
| action |
GPIO pin |
value |
don’t care |
don’t care |
Command message values
| action |
GPIO pin |
value |
Description |
| 0x30 |
0x01 |
- |
Read value of GPIO pin 1 |
| 0x30 |
0x02 |
- |
Read value of GPIO pin 2 |
| 0x30 |
0x03 |
- |
Read value of GPIO pin 3 |
| 0x31 |
0x01 |
0x01 |
Write value 1 to GPIO pin 1 |
| 0x31 |
0x01 |
0x00 |
Write value 0 to GPIO pin 1 |
| 0x31 |
0x02 |
0x01 |
Write value 1 to GPIO pin 2 |
| 0x31 |
0x02 |
0x00 |
Write value 0 to GPIO pin 2 |
| 0x31 |
0x03 |
0x01 |
Write value 1 to GPIO pin 3 |
| 0x31 |
0x03 |
0x00 |
Write value 0 to GPIO pin 3 |
Response message structure
| byte 0 |
byte 1 |
byte 2 |
byte 3 |
… |
byte 63 |
| status |
action |
GPIO pin |
value |
don’t care |
don’t care |
Response message values
| status |
action |
GPIO pin |
value |
Command description |
| 0x01 |
0x30 |
0x01 |
0x01 |
GPIO pin 1 is at value 1 |
| 0x01 |
0x30 |
0x01 |
0x00 |
GPIO pin 1 is at value 0 |
| 0x01 |
0x30 |
0x02 |
0x01 |
GPIO pin 2 is at value 1 |
| 0x01 |
0x30 |
0x02 |
0x00 |
GPIO pin 2 is at value 0 |
| 0x01 |
0x30 |
0x03 |
0x01 |
GPIO pin 2 is at value 1 |
| 0x01 |
0x30 |
0x03 |
0x01 |
GPIO pin 3 is at value 1 |
| 0x01 |
0x30 |
0x03 |
0x00 |
GPIO pin 3 is at value 0 |
| 0x01 |
0x31 |
0x01 |
0x01 |
GPIO pin 1 was set to value 1 |
| 0x01 |
0x31 |
0x01 |
0x00 |
GPIO pin 1 was set to value 0 |
| 0x01 |
0x31 |
0x02 |
0x01 |
GPIO pin 2 was set to value 1 |
| 0x01 |
0x31 |
0x02 |
0x00 |
GPIO pin 2 was set to value 0 |
| 0x01 |
0x31 |
0x03 |
0x01 |
GPIO pin 3 was set to value 1 |
| 0x01 |
0x31 |
0x03 |
0x00 |
GPIO pin 3 was set to value 0 |
GPIO control interface enable or disable
Enable or disable the GPIO as a control interface.
When enabled the pins are configured as digital inputs and the corresponding numbered downstream port state will be set according to the digital level on the pin.
Command message structure
| byte 0 |
byte 1 |
… |
byte 63 |
| 0x32 |
action |
don’t care |
don’t care |
Command message values
| action |
Command description |
| 0x01 |
Enable GPIO control interface |
| 0x00 |
Disable GPIO control interface |
Response message structure
| byte 0 |
byte 1 |
byte 2 |
… |
byte 63 |
| status |
0x32 |
action |
don’t care |
don’t care |
Response message values
| status |
control byte |
action |
description |
|
| 0x01 |
0x32 |
0x01 |
GPIO control interface enabled |
|
| 0x01 |
0x32 |
0x00 |
GPIO control interface enabled |
|
| 0x00 |
- |
- |
Error |
|
Downstream port default state configuration
Configuration of downstream port default state.
On reset or power-on the ports are set to the defined default state.
Command message structure
| byte 0 |
byte 1 |
byte 2 |
… |
byte 63 |
| 0x41 |
port |
default state |
don’t care |
don’t care |
Command message values
| port |
default state |
command description |
| 0x01 |
0x00 |
Set port 1 default state to Off |
| 0x01 |
0x01 |
Set port 1 default state to On |
| 0x02 |
0x00 |
Set port 2 default state to Off |
| 0x02 |
0x01 |
Set port 2 default state to On |
| 0x03 |
0x00 |
Set port 3 default state to Off |
| 0x03 |
0x01 |
Set port 3 default state to On |
Response message structure
| byte 0 |
byte 1 |
byte 2 |
byte 3 |
… |
byte 63 |
| status |
0x41 |
port |
default state |
don’t care |
don’t care |
Response message values
| status |
port |
default state |
command description |
| 0x01 |
0x01 |
0x00 |
Port 1 default state set to Off |
| 0x01 |
0x01 |
0x01 |
Port 1 default state set to On |
| 0x01 |
0x02 |
0x00 |
Port 2 default state set to Off |
| 0x01 |
0x02 |
0x01 |
Port 2 default state set to On |
| 0x01 |
0x03 |
0x00 |
Port 3 default state set to Off |
| 0x01 |
0x03 |
0x01 |
Port 3 default state set to On |
| 0x00 |
- |
- |
Error |
Trigger bootloader mode for firmware update
Command the board to enter into the bootloader mode for a firmware update.
| byte 0 |
… |
byte 63 |
| 0x42 |
don’t care |
don’t care |
I2C interface configuration
I2C interface can be configured to slave or master mode.
When configured to slave mode the I2C becomes a control interface.
Check the I2C section
When in master mode the I2C becomes a host USB-to-I2C gateway.
Check the I2C section
These configurations are persistent and will endure resets and power cycles
Command message structure
| byte 0 |
byte 1 |
byte 2 |
… |
byte 63 |
| 0x51 |
action |
value |
don’t care |
don’t care |
Command message values
| action |
value |
command description |
| 0x01 |
0x00 |
Disable I2C slave mode |
| 0x01 |
0x01 |
Enable I2C slave mode |
| 0x02 |
0x00 |
Disable I2C master mode |
| 0x02 |
0x01 |
Enable I2C master mode |
| 0x03 |
i2c_addr |
Configures the board I2C slave address with value i2c_addr |
Response message structure
| byte 0 |
… |
byte 63 |
| status |
don’t care |
don’t care |
Response message values
| status |
description |
| 0x01 |
Success |
| 0x00 |
Error |
Host USB-to-I2C gateway commands
With I2C master mode enabled, read and write commands are made available
to the USB host.
They allow to write and read an arbitrary number of bytes to
or from the I2C slave devices.
Command message structure
| byte 0 |
byte 1 |
byte 2 |
byte 3 |
byte 4 |
… |
byte 63 |
| 0x52 |
action |
i2c_address |
n_bytes |
buff_0 |
don’t care |
don’t care |
Where:
-
action is a write or read action code. 0x01 is a write and 0x02 is a read.
-
i2c_address is the 7 bit slave address aligned to the most significant bit
and with the byte least significant bit at zero. For example, 0b10100110
byte represents the I2C address 0b1010011.
-
n_bytes is the number of bytes to read from or written to the slave
device.
-
buff_0 is the first byte of the buffer containing the data to be written or
where the read data should be stored.
An example where the USB host transmits two bytes, 0x11 and 0x22,
to I2C slave device with 7 bit address 0x1111111 using the YKUSH3 as a bridge.
The command for this example is the following.
| byte 0 |
byte 1 |
byte 2 |
byte 3 |
byte 4 |
byte 5 |
… |
| 0x52 |
0x01 |
0x11111110 |
0x02 |
0x11 |
0x22 |
- |
In the case of a successful write the following response is received by the
USB host from the YKUSH3.
| byte 0 |
byte 1 |
… |
| 0x01 |
0x52 |
- |
The response message structure, for both write and read commands, is the
following.
| byte 0 |
byte 1 |
byte 2 |
byte 3 |
… |
| status |
0x52 |
n_bytes |
data byte 1 |
… |
Where:
-
status is 0x01 on success, 0x02 error due to board not being set to I2C
master mode or 0x03 I2C transmission error.
-
n_bytes is the number of data bytes to be transmitted, on a write
command, or the number of data bytes received on a read command.
-
data-byte-x is the data byte received from the I2C slave device in the
case on a read command. For write command responses this bytes are not
used.
Reset command
Command to trigger the board reset.
| byte 0 |
… |
byte 63 |
| 0x55 |
- |
- |
Get bootloader and firmware version
Version information of the bootloader and firmware is obtained using the commands presented here.
Command message structure
| byte 0 |
byte 1 |
… |
byte 63 |
| 0x61 |
subject |
- |
- |
subject defines if the command is for the bootloader or firmware version.
0x01 is for bootloader and 0x02 for firmware.
Response message structure
| byte 0 |
byte 1 |
byte 2 |
byte 3 |
byte 4 |
… |
byte 63 |
| status |
0x61 |
major |
minor |
patch |
- |
- |
Where:
status 0x01 for success and 0x00 for errormajor version numberminor version numberpatch version number