Difference between revisions of "Component: USB HID (Comms: USB)"

Latest revision as of 17:24, 9 November 2022

Author	Matrix Ltd
Version	1.4
Category	Comms: USB

USB HID component

Component to create and communicate using a standard HID type USB class. Compatible with simulation and USB enabled microcontroller devices PIC/dsPIC/AVR. Note that AVR is currently in Beta and may have problems with custom descriptors.

Component Pack

COMMSC

Detailed description

No detailed description exists yet for this component

Examples

Here are some examples to get you started with USB HID communications using Flowcode.

HID Mouse

Reads a EB014 keypad and depending on the key pressed sends the appropriate movement and button clicks to control the mouse.

The speed is set by the speed variable which can range from 1 to 127.

Mouse Keypad Example

Key breakdown: 1 = UpLeft, 2=Up, 3=UpRight, 4=Left, 6=Right, 7=DownLeft, 8=Down, 9=DownRight, *=Left Click, #=Right Click.

Reads two encoders and moves the mouse cursor based on their movement since the last operation.

A switch on pin B0 can be used to toggle the left mouse click on and off and pin B1 can be connected to an LED to show the status of the left mouse button.

The EB073 encoders board connected to PortB will allow all of this functionality.

Mouse Encoder Example

HID Keyboard

Converts a ASCII character into a keypress that will be sent to the USB host device.

A demo string is provided which is then broken down into characters and sent to the USB host.

Keyboard Example

Here is a file showing the standard HID keyboard scan codes to help make sense of the example.

File:HID Keyboard Scan Codes.xls

With the example running if you create a text file and highlight the text file then the USB device will populate the file with data.

E.g.

HelloFromYourUSBKeyboardDevice12345

Currently only compatible with the following characters: 0123456789!"£$%^&*()/\*-+ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz\n\t

A complete list of keyboard scan codes can be found here under section 7 - Keyboards.

http://www.freebsddiary.org/APC/usb_hid_usages.php

HID Descriptor Tool

This tool allows you to create your own descriptors which can then be inserted into the HID descriptor property with the custom descriptor type selected.

File:HID Descriptor Tool.zip

Downloadable macro reference

	ReceiveByte
Receives a byte from the USB.
- BYTE	Idx

- BYTE	Return

	SetSerialNumber
Allows the device serial number to be edited.
- STRING	SerialNumber

- VOID	Return

	SendData
Sends the contents of the transmit buffer to the USB.
- BYTE	Return

	CheckRx
Checks for any incoming data. Returns the number of data bytes received since the last check.
- BYTE	Return

	UpdateData
Allows a byte of the transmit buffer to be assigned.
- BYTE	idx

- BYTE	value

- VOID	Return

	ReceiveString
Receives a string of bytes from the USB
- BYTE	NumBytes

- STRING	Return

	SendDataDirect
Sends data directly to the USB
- STRING	Data

- BYTE	Return

	Initialise
Starts up the USB connection and waits for the device driver to be correctly installed on the PC.
- BYTE	Return

Property reference

	Properties
	USB Properties
	Vendor ID
USB vendor identifier tied to the manufacturer of the USB device
	Product ID
USB product identifier
	Device Name
Name used to identify the device
	Manufacturer
Manufacturer of the device
	Major Version
Firmware major version
	Minor Version
Device firmware minor version
	Enumeration Timeout
Specifies if the initialise routine is allowed to timeout instead of waiting forever for success
	Maximum Current (mA)
Maximum current the host should source to the device - max 500mA
	Country Code
Specific country code - if required
	Descriptor Select
Built in descriptor selection
	HID Descriptor
Contents of the HID descriptor
	Subclass
USB Subclass - Normally only mice and keyboards are boot devices
	Interface
Standard HID interface type
	Transmit Packet Size
Number of bytes to send to the PC
	Transmit Period (ms)
Delay between transmit packets
	Receive Packet Size
Number of bytes to receive from the PC
	Receive Period (ms)
Delay between receive packets
	Simulation
	Label
Simulation label used to indicate the USB HID component on the panel.

Difference between revisions of "Component: USB HID (Comms: USB)"

Latest revision as of 17:24, 9 November 2022

Contents

USB HID component

Component Pack

Detailed description

Examples

HID Mouse

HID Keyboard

HID Descriptor Tool

Downloadable macro reference

Property reference

Navigation menu

Page actions

Page actions

Personal tools

Navigation

Search

Tools

@@ Line 1: / Line 1: @@
+{| style="width:50%"
-{| width="50%"
 |-
-| width="20%" style="color: gray;" | Author
+| width="20%" style="color:gray;" | Author
 | Matrix Ltd
 |-
-| width="20%" style="color: gray;" | Version
+| width="20%" style="color:gray;" | Version
-| 1.3 (Release)
+| 1.4
 |-
-| width="20%" style="color: gray;" | Category
+| width="20%" style="color:gray;" | Category
 | Comms: USB
 |}
+==USB HID component==
+Component to create and communicate using a standard HID type USB class. Compatible with simulation and USB enabled microcontroller devices PIC/dsPIC/AVR. Note that AVR is currently in Beta and may have problems with custom descriptors.
-==[[File:Component Icon 06a0a9b3_dd23_4592_a781_537a31b97c2a.png|Image]] USB HID component==
+==Component Pack==
-Component to create and communicate using a standard HID type USB class.
-Compatible with simulation and USB enabled microcontroller devices PIC/dsPIC/AVR.
-Note that AVR is currently in Beta and may have problems with custom descriptors.
-==Examples==
+COMMSC
-''<span style="color:red;">No additional examples</span>''
+==Detailed description==
-==Downloadable macro reference==
-===<span style="font-weight: normal;"><u><tt>ReceiveByte</tt></u></span>===
-Receives a byte from the USB.
-'''Parameters'''
-:[[Variable Types|BYTE]] ''Idx''
-'''Return value'''
-:[[Variable Types|BYTE]]
-===<span style="font-weight: normal;"><u><tt>SetSerialNumber</tt></u></span>===
-Allows the device serial number to be edited.
-'''Parameters'''
-:[[Variable Types|<- STRING]] ''SerialNumber''
-::''This parameter may be returned back to the caller''
-'''Return value'''
+''No detailed description exists yet for this component''
-:''This call does not return a value''
+==Examples==
-===<span style="font-weight: normal;"><u><tt>SendData</tt></u></span>===
-Sends the contents of the transmit buffer to the USB.
-'''Parameters'''
-:''This macro has no parameters''
-'''Return value'''
-:[[Variable Types|BYTE]]
-===<span style="font-weight: normal;"><u><tt>CheckRx</tt></u></span>===
-Checks for any incoming data.
-Returns the number of data bytes received since the last check.
-'''Parameters'''
-:''This macro has no parameters''
-'''Return value'''
+Here are some examples to get you started with USB HID communications using Flowcode.
-:[[Variable Types|BYTE]]
+===HID Mouse===
+Reads a EB014 keypad and depending on the key pressed sends the appropriate movement and button clicks to control the mouse.
-===<span style="font-weight: normal;"><u><tt>UpdateData</tt></u></span>===
+The speed is set by the speed variable which can range from 1 to 127.
-Allows a byte of the transmit buffer to be assigned.
-'''Parameters'''
+{{Fcfile|USB_HID_Mouse.fcfx|Mouse Keypad Example}}
-:[[Variable Types|BYTE]] ''idx''
+Key breakdown: 1 = UpLeft, 2=Up, 3=UpRight, 4=Left, 6=Right, 7=DownLeft, 8=Down, 9=DownRight, *=Left Click, #=Right Click.
-:[[Variable Types|BYTE]] ''value''
+Reads two encoders and moves the mouse cursor based on their movement since the last operation.
-'''Return value'''
+A switch on pin B0 can be used to toggle the left mouse click on and off and pin B1 can be connected to an LED to show the status of the left mouse button.
-:''This call does not return a value''
+The EB073 encoders board connected to PortB will allow all of this functionality.
-===<span style="font-weight: normal;"><u><tt>ReceiveString</tt></u></span>===
+{{Fcfile|USB_HID_Etch_A_Sketch.fcfx|Mouse Encoder Example}}
-Receives a string of bytes from the USB
-'''Parameters'''
-:[[Variable Types|BYTE]] ''NumBytes''
+===HID Keyboard===
+Converts a ASCII character into a keypress that will be sent to the USB host device.
-'''Return value'''
+A demo string is provided which is then broken down into characters and sent to the USB host.
-:[[Variable Types|STRING]]
+{{Fcfile|USB_HID_Keyboard.fcfx|Keyboard Example}}
-===<span style="font-weight: normal;"><u><tt>SendDataDirect</tt></u></span>===
+Here is a file showing the standard HID keyboard scan codes to help make sense of the example.
-Sends data directly to the USB
-'''Parameters'''
+[[File:HID Keyboard Scan Codes.xls]]
-:[[Variable Types|<- STRING]] ''Data''
-::''This parameter may be returned back to the caller''
+With the example running if you create a text file and highlight the text file then the USB device will populate the file with data.
-'''Return value'''
-:[[Variable Types|BYTE]]
+E.g.
+HelloFromYourUSBKeyboardDevice12345
-===<span style="font-weight: normal;"><u><tt>Initialise</tt></u></span>===
+HelloFromYourUSBKeyboardDevice12345
-Starts up the USB connection and waits for the device driver to be correctly installed on the PC.
-'''Parameters'''
+HelloFromYourUSBKeyboardDevice12345
-:''This macro has no parameters''
+Currently only compatible with the following characters: 0123456789!"£$%^&*()/\*-+ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz\n\t
-'''Return value'''
-:[[Variable Types|BYTE]]
+A complete list of keyboard scan codes can be found here under section 7 - Keyboards.
+http://www.freebsddiary.org/APC/usb_hid_usages.php
-==Simulation macro reference==
+===HID Descriptor Tool===
-''This component does not contain any simulation macros''
+This tool allows you to create your own descriptors which can then be inserted into the HID descriptor property with the custom descriptor type selected.
+[[File:HID Descriptor Tool.zip]]
-==Property reference==
+==Downloadable macro reference==
-<span style="font-weight: normal;"><u>Vendor ID</u></span>
-This property is of type ''Signed integer'' and can be referenced with the variable name ''vendor_ID''.
+{| class="wikitable" style="width:60%; background-color:#FFFFFF;"
+|-
+| width="10%" align="center" style="background-color:#D8C9D8;" align="center" | [[File:Fc9-comp-macro.png]]
+| width="90%" style="background-color:#D8C9D8; color:#4B008D;" | '''ReceiveByte'''
+|-
+| colspan="2" | Receives a byte from the USB.&nbsp;
+|-
+|-
+| width="10%" align="center" | [[File:Fc9-u8-icon.png]] - BYTE
+| width="90%" | Idx
+|-
+| colspan="2" | &nbsp;
+|-
+| width="10%" align="center" style="border-top: 2px solid #000;" | [[File:Fc9-u8-icon.png]] - BYTE
+| width="90%" style="border-top: 2px solid #000;" | ''Return''
+|}
-USB vendor identifier tied to the manufacturer of the USB device
-<span style="font-weight: normal;"><u>Product ID</u></span>
+{| class="wikitable" style="width:60%; background-color:#FFFFFF;"
+|-
+| width="10%" align="center" style="background-color:#D8C9D8;" align="center" | [[File:Fc9-comp-macro.png]]
+| width="90%" style="background-color:#D8C9D8; color:#4B008D;" | '''SetSerialNumber'''
+|-
+| colspan="2" | Allows the device serial number to be edited.&nbsp;
+|-
+|-
+| width="10%" align="center" | [[File:Fc9-string-icon.png]] - STRING
+| width="90%" | SerialNumber
+|-
+| colspan="2" | &nbsp;
+|-
+| width="10%" align="center" style="border-top: 2px solid #000;" | [[File:Fc9-void-icon.png]] - VOID
+| width="90%" style="border-top: 2px solid #000;" | ''Return''
+|}
-This property is of type ''Signed integer'' and can be referenced with the variable name ''product_ID''.
-USB product identifier
+{| class="wikitable" style="width:60%; background-color:#FFFFFF;"
+|-
+| width="10%" align="center" style="background-color:#D8C9D8;" align="center" | [[File:Fc9-comp-macro.png]]
+| width="90%" style="background-color:#D8C9D8; color:#4B008D;" | '''SendData'''
+|-
+| colspan="2" | Sends the contents of the transmit buffer to the USB.&nbsp;
+|-
+|-
+| width="10%" align="center" style="border-top: 2px solid #000;" | [[File:Fc9-u8-icon.png]] - BYTE
+| width="90%" style="border-top: 2px solid #000;" | ''Return''
+|}
-<span style="font-weight: normal;"><u>Device Name</u></span>
-This property is of type ''Line of text'' and can be referenced with the variable name ''dev_name''.
+{| class="wikitable" style="width:60%; background-color:#FFFFFF;"
+|-
+| width="10%" align="center" style="background-color:#D8C9D8;" align="center" | [[File:Fc9-comp-macro.png]]
+| width="90%" style="background-color:#D8C9D8; color:#4B008D;" | '''CheckRx'''
+|-
+| colspan="2" | Checks for any incoming data. Returns the number of data bytes received since the last check.&nbsp;
+|-
+|-
+| width="10%" align="center" style="border-top: 2px solid #000;" | [[File:Fc9-u8-icon.png]] - BYTE
+| width="90%" style="border-top: 2px solid #000;" | ''Return''
+|}
-Name used to identify the device
-<span style="font-weight: normal;"><u>Manufacturer</u></span>
+{| class="wikitable" style="width:60%; background-color:#FFFFFF;"
+|-
+| width="10%" align="center" style="background-color:#D8C9D8;" align="center" | [[File:Fc9-comp-macro.png]]
+| width="90%" style="background-color:#D8C9D8; color:#4B008D;" | '''UpdateData'''
+|-
+| colspan="2" | Allows a byte of the transmit buffer to be assigned.&nbsp;
+|-
+|-
+| width="10%" align="center" | [[File:Fc9-u8-icon.png]] - BYTE
+| width="90%" | idx
+|-
+| colspan="2" | &nbsp;
+|-
+| width="10%" align="center" | [[File:Fc9-u8-icon.png]] - BYTE
+| width="90%" | value
+|-
+| colspan="2" | &nbsp;
+|-
+| width="10%" align="center" style="border-top: 2px solid #000;" | [[File:Fc9-void-icon.png]] - VOID
+| width="90%" style="border-top: 2px solid #000;" | ''Return''
+|}
-This property is of type ''Line of text'' and can be referenced with the variable name ''dev_manufacturer''.
-Manufacturer of the device
+{| class="wikitable" style="width:60%; background-color:#FFFFFF;"
+|-
+| width="10%" align="center" style="background-color:#D8C9D8;" align="center" | [[File:Fc9-comp-macro.png]]
+| width="90%" style="background-color:#D8C9D8; color:#4B008D;" | '''ReceiveString'''
+|-
+| colspan="2" | Receives a string of bytes from the USB&nbsp;
+|-
+|-
+| width="10%" align="center" | [[File:Fc9-u8-icon.png]] - BYTE
+| width="90%" | NumBytes
+|-
+| colspan="2" | &nbsp;
+|-
+| width="10%" align="center" style="border-top: 2px solid #000;" | [[File:Fc9-string-icon.png]] - STRING
+| width="90%" style="border-top: 2px solid #000;" | ''Return''
+|}
-<span style="font-weight: normal;"><u>Major Version</u></span>
-This property is of type ''Signed integer'' and can be referenced with the variable name ''major_version''.
+{| class="wikitable" style="width:60%; background-color:#FFFFFF;"
+|-
+| width="10%" align="center" style="background-color:#D8C9D8;" align="center" | [[File:Fc9-comp-macro.png]]
+| width="90%" style="background-color:#D8C9D8; color:#4B008D;" | '''SendDataDirect'''
+|-
+| colspan="2" | Sends data directly to the USB&nbsp;
+|-
+|-
+| width="10%" align="center" | [[File:Fc9-string-icon.png]] - STRING
+| width="90%" | Data
+|-
+| colspan="2" | &nbsp;
+|-
+| width="10%" align="center" style="border-top: 2px solid #000;" | [[File:Fc9-u8-icon.png]] - BYTE
+| width="90%" style="border-top: 2px solid #000;" | ''Return''
+|}
-Firmware major version
-<span style="font-weight: normal;"><u>Minor Version</u></span>
+{| class="wikitable" style="width:60%; background-color:#FFFFFF;"
+|-
+| width="10%" align="center" style="background-color:#D8C9D8;" align="center" | [[File:Fc9-comp-macro.png]]
+| width="90%" style="background-color:#D8C9D8; color:#4B008D;" | '''Initialise'''
+|-
+| colspan="2" | Starts up the USB connection and waits for the device driver to be correctly installed on the PC. &nbsp;
+|-
+|-
+| width="10%" align="center" style="border-top: 2px solid #000;" | [[File:Fc9-u8-icon.png]] - BYTE
+| width="90%" style="border-top: 2px solid #000;" | ''Return''
+|}
-This property is of type ''Signed integer'' and can be referenced with the variable name ''minor_version''.
-Device firmware minor version
-<span style="font-weight: normal;"><u>Enumeration Timeout</u></span>
-This property is of type ''True or false'' and can be referenced with the variable name ''enumeration_tout''.
+==Property reference==
-Specifies if the initialise routine is allowed to timeout instead of waiting forever for success
+{| class="wikitable" style="width:60%; background-color:#FFFFFF;"
+|-
-<span style="font-weight: normal;"><u>Maximum Current (mA)</u></span>
+| width="10%" align="center" style="background-color:#D8C9D8;" | [[File:Fc9-prop-icon.png]]
+| width="90%" style="background-color:#D8C9D8; color:#4B008D;" | '''Properties'''
-This property is of type ''Signed integer'' and can be referenced with the variable name ''max_current''.
+|-
+|-
-Maximum current the host should source to the device - max 500mA
+| width="10%" align="center" style="background-color:#EAE1EA;" | [[File:Fc9-conn-icon.png]]
+| width="90%" style="background-color:#EAE1EA; color:#4B008D;" | USB Properties
-<span style="font-weight: normal;"><u>Country Code</u></span>
+|-
+|-
-This property is of type ''Fixed list of ints'' and can be referenced with the variable name ''cntry_code''.
+| width="10%" align="center" | [[File:Fc9-type-21-icon.png]]
+| width="90%" | Vendor ID
-Specific country code - if required
+|-
+| colspan="2" | USB vendor identifier tied to the manufacturer of the USB device&nbsp;
-<span style="font-weight: normal;"><u>Descriptor Select</u></span>
+|-
+| width="10%" align="center" | [[File:Fc9-type-21-icon.png]]
-This property is of type ''Fixed list of ints'' and can be referenced with the variable name ''descriptor_Select''.
+| width="90%" | Product ID
+|-
-Built in descriptor selection
+| colspan="2" | USB product identifier&nbsp;
+|-
-<span style="font-weight: normal;"><u>HID Descriptor</u></span>
+| width="10%" align="center" | [[File:Fc9-type-10-icon.png]]
+| width="90%" | Device Name
-This property is of type ''Multiple lines of text'' and can be referenced with the variable name ''HID_descriptor''.
+|-
+| colspan="2" | Name used to identify the device&nbsp;
-Contents of the HID descriptor
+|-
+| width="10%" align="center" | [[File:Fc9-type-10-icon.png]]
-<span style="font-weight: normal;"><u>Subclass</u></span>
+| width="90%" | Manufacturer
+|-
-This property is of type ''Fixed list of ints'' and can be referenced with the variable name ''subclass''.
+| colspan="2" | Manufacturer of the device&nbsp;
+|-
-USB Subclass - Normally only mice and keyboards are boot devices
+| width="10%" align="center" | [[File:Fc9-type-14-icon.png]]
+| width="90%" | Major Version
-<span style="font-weight: normal;"><u>Interface</u></span>
+|-
+| colspan="2" | Firmware major version&nbsp;
-This property is of type ''Fixed list of ints'' and can be referenced with the variable name ''interface''.
+|-
+| width="10%" align="center" | [[File:Fc9-type-14-icon.png]]
-Standard HID interface type
+| width="90%" | Minor Version
+|-
-<span style="font-weight: normal;"><u>Transmit Packet Size</u></span>
+| colspan="2" | Device firmware minor version &nbsp;
+|-
-This property is of type ''Signed integer'' and can be referenced with the variable name ''tx_packet_size''.
+| width="10%" align="center" | [[File:Fc9-type-7-icon.png]]
+| width="90%" | Enumeration Timeout
-Number of bytes to send to the PC
+|-
+| colspan="2" | Specifies if the initialise routine is allowed to timeout instead of waiting forever for success&nbsp;
-<span style="font-weight: normal;"><u>Transmit Period (ms)</u></span>
+|-
+| width="10%" align="center" | [[File:Fc9-type-14-icon.png]]
-This property is of type ''Signed integer'' and can be referenced with the variable name ''tx_period''.
+| width="90%" | Maximum Current (mA)
+|-
-Delay between transmit packets
+| colspan="2" | Maximum current the host should source to the device - max 500mA&nbsp;
+|-
-<span style="font-weight: normal;"><u>Receive Packet Size</u></span>
+| width="10%" align="center" | [[File:Fc9-type-16-icon.png]]
+| width="90%" | Country Code
-This property is of type ''Signed integer'' and can be referenced with the variable name ''rx_packet_size''.
+|-
+| colspan="2" | Specific country code - if required&nbsp;
-Number of bytes to receive from the PC
+|-
+| width="10%" align="center" | [[File:Fc9-type-16-icon.png]]
-<span style="font-weight: normal;"><u>Receive Period (ms)</u></span>
+| width="90%" | Descriptor Select
+|-
-This property is of type ''Signed integer'' and can be referenced with the variable name ''rx_period''.
+| colspan="2" | Built in descriptor selection &nbsp;
+|-
-Delay between receive packets
+| width="10%" align="center" | [[File:Fc9-type-11-icon.png]]
+| width="90%" | HID Descriptor
-<span style="font-weight: normal;"><u>Label</u></span>
+|-
+| colspan="2" | Contents of the HID descriptor&nbsp;
-This property is of type ''Line of text'' and can be referenced with the variable name ''label''.
+|-
+| width="10%" align="center" | [[File:Fc9-type-16-icon.png]]
-Simulation label used to indicate the USB HID component on the panel.
+| width="90%" | Subclass
+|-
+| colspan="2" | USB Subclass - Normally only mice and keyboards are boot devices&nbsp;
+|-
+| width="10%" align="center" | [[File:Fc9-type-16-icon.png]]
+| width="90%" | Interface
+|-
+| colspan="2" | Standard HID interface type&nbsp;
+|-
+| width="10%" align="center" | [[File:Fc9-type-14-icon.png]]
+| width="90%" | Transmit Packet Size
+|-
+| colspan="2" | Number of bytes to send to the PC &nbsp;
+|-
+| width="10%" align="center" | [[File:Fc9-type-14-icon.png]]
+| width="90%" | Transmit Period (ms)
+|-
+| colspan="2" | Delay between transmit packets&nbsp;
+|-
+| width="10%" align="center" | [[File:Fc9-type-14-icon.png]]
+| width="90%" | Receive Packet Size
+|-
+| colspan="2" | Number of bytes to receive from the PC&nbsp;
+|-
+| width="10%" align="center" | [[File:Fc9-type-14-icon.png]]
+| width="90%" | Receive Period (ms)
+|-
+| colspan="2" | Delay between receive packets&nbsp;
+|-
+| width="10%" align="center" style="background-color:#EAE1EA;" | [[File:Fc9-conn-icon.png]]
+| width="90%" style="background-color:#EAE1EA; color:#4B008D;" | Simulation
+|-
+|-
+| width="10%" align="center" | [[File:Fc9-type-10-icon.png]]
+| width="90%" | Label
+|-
+| colspan="2" | Simulation label used to indicate the USB HID component on the panel.&nbsp;
+|}