# Microcontroller Configuration Description (MCD) Files

Generic HID is a GUI editor that provides a friendly way of generating MCD files. MCD files provide the low level details that describe how buttons and joysticks are connected to the microcontroller and how they appear as a HID device.

## Structure

MCD files are XML files. They have the following required tags.

`<!DOCTYPE GenericHIDDevice>
<GenericHIDDevice>
<Device />
<Configuration />
<Controls>
</Controls>
</GenericHIDDevice>
`

## <GenericHIDDevice>

This tag is the root node of the XML tree. It has no attributes. All other nodes are children of this tag. The tag is required.

## <Device>

The device tag describes device attributes. It is a required node. The device attributes are aligned with the USB Device Descriptor.

### Attributes

VID | The USB Vendor ID. This is a 16bit integer. The value can be decimal, or hexadecimal (prefixed with an 'x')
PID | The USB Product ID. This is a 16bit integer. The value can be decimal, or hexadecimal (prefixed with an 'x')
Release | This is the release version number of the device. This is a 16bit integer. The value can be decimal, or hexadecimal (prefixed with an 'x')
Manufacturer | The manufacturer string. This is a USB string, maximum length of 127 bytes.
Product | The product string. This is a USB string, maximum length of 127 bytes.
SerialNo | The serial number of the device as a string. This is a USB string, maximum length of 127 bytes.

## <Configuration>

The configuration tag describes the device configuration. It is a required node. The configuration attributes are loosely aligned with the USB Config Descriptor.

### Attributes

BusPowered | true/false if the device is bus powered, otherwise it is self powered.
PowerConsumption | The power consumption of the device in mA.
Interval | The requested poll interval, in ms.
is5Volt | true if the microcontroller is powered by 5 volts, false if it is 3.3 volts. If it is 5 volts, the internal voltage regulator is enabled to provide the 3.3 volts need to communicate on the USB bus.
UseStatusLEDs | An enumerated type. One of LED1, LED2, Both, or None. Tells the microcontroller to use the LEDs as status indicators.
SerialDebug | true/false to enable serial debug. When enabled, I/O pins PD2/PD3 are set up as serial communication pins RX/TX. The ports are only used for output at 38400,8,n,1
HIDDebug | true/false to enable HID debug. This isn't implemented.
UsagePage | The device usage page. The value can be decimal, or hexadecimal (prefixed with an 'x')
Usage | The device usage. The value can be decimal, or hexadecimal (prefixed with an 'x')
PowerPort | Optional attribute specifying which I/O port PA0-PF7 is used as the HiPower switch. If no HiPower switch is used, do not specify this attribute.
Timer1 | Settings for Timer1. Timer settings are in the format [mode],[prescaler],[count top], where mode is 0 for phase correct mode or 1 for fast PWM mode, prescaler is one of the valid device prescale values, and count top is the counter top value. The Timer1 attribute specifies settings for Timer/Counter 1.
Timer2 | Settings for Timer/Counter 2, as for Timer1.
Timer3 | Settings for Timer/Counter 3, as for Timer1.

## <Controls>

The controls tag is a collection of nodes describing each device connected to the microcontroller. There can be zero or more device nodes. The following sections describe the devices that can be collected under the controls node.

## <DirectionalSwitch>

Used to specify a directional joystick or hat switch. HID returns a value of -1 for not selected, or 0-max indicating which switches are pressed. The physical min/max are used to convert these values to an angle.

### Attributes

Name | Optonial descriptive text name.
UsagePage | The usage page of the control.
Usage | The usage of the control.
Pullup | true/false if the internal pull-up resistors should be used on all pins.
Debounce | true/false if the inputs should be debounced.
Directions | The number of directions - one of "2way NS", "2way WE", "4way", "8way"
PortN | Specifies the port if the device has a N direction. One of PA0..PF7.
PortS | Specifies the port if the device has a S direction. One of PA0..PF7.
PortW | Specifies the port if the device has a W direction. One of PA0..PF7.
PortE | Specifies the port if the device has a E direction. One of PA0..PF7.
PortNW | Specifies the port if the device has a NW direction. One of PA0..PF7.
PortNE | Specifies the port if the device has a NE direction. One of PA0..PF7.
PortSW | Specifies the port if the device has a SW direction. One of PA0..PF7.
PortSE | Specifies the port if the device has a SE direction. One of PA0..PF7.

##
<AnalogIn>

A generic analogue input. Usually used for potentiometer inputs, but digital analouge inputs can be used as well.

### Attributes

Name | Optonial descriptive text name.
UsagePage | The usage page of the control.
Usage | The usage of the control.
Bits | The number of bits to return the data in. 1-10. The internal ADCs always convert to 10 bits, but less bits can be specified to pack more data into the HID Input Report.

##
<Switch>

Used to specify a simple switch, although it can be used for a digital inputs.

### Attributes

Name | Optional descriptive text name.
UsagePage | The usage page of the control.
Usage | The usage of the control.
Port | Which I/O port is the input connected to. One of PA0..PF7.
Pullup | true/false if the internal pull up resistor should be used.
Debounce | true/false if debounce logic should be used on this input.

##
<TricolourLED>

Used to describe a tri-colour LED. This is a 2 bit (4 value) HID output.

### Attributes

Name | Optional descriptive text name.
UsagePage | The usage page of the control.
Usage | The usage of the control.
PortA | The I/O port leg 1 of the LED is connected to. One of PA0..PF7.
PortB | The I/O port leg 1 of the LED is connected to. One of PA0..PF7.
Source | true/false if the microcontroller sources current, or sinks it.

##
<DigitalEncoder>

Defines a digital encoder. The device is defined as an 8 bit HID input value, relative, with wrapping. This means it counts in an 8 bit buffer and wraps when it underflows or overflows.

### Attributes

Name | Optional descriptive text name.
UsagePage | The usage page of the control.
Usage | The usage of the control.
PortA | The I/O port Pin A of the encoder is connected to. One of PA0..PF7.
PortB | The I/O port Pin B of the encoder is connected to. One of PA0..PF7.

##
<KeyMatrix>

Defines a key matrix, either a pre-assembled keypad, or a matrix board to add many buttons, but use fewer pins. Internally, the microcontroller will strobe the columns and read the rows. The KeyMatrix tag has child nodes that identify the rows and columns that make up the matrix. Each key can be optionally named.

### Attributes

UsagePage | The usage page of the control.
UsageMin | The minimum usage value of the control. Each key defined in the matrix will be allocated a consecutive number starting at UsageMin.
Debounce | true/false to debounce the key strokes.

### <ColOut>

Defines a column that makes up the matrix. Columns are the output strobes.

#### Attributes

Port | The I/O pin that this column is connected to. One of PA0..PF7.

### <RowIn>

Defines a row that makes up the matrix. As the columns are strobed, the rows are read.

#### Attributes

Port | The I/O pin that this row is connected to. One of PA0..PF7.

### <Key>

Defines a key label. This is optional. Keys without labels still have a usage value.

#### Attributes

Row | Which row is this key on.
Col | Which column is this key on.
Name | The text description of the key.

##
<RotarySwitch>

Defines a rotary selector switch. This appears as an n-bit input value. The number of bits is determined by the number of inputs. If the switch is coded, the output is converted to a binary number, and only Log2(n)+1 bits are required. The RotarySwitch tag contains child nodes which identify the input pins, and which bits they refer to.

### Attributes

Name | Optional descriptive text name.
UsagePage | The usage page of the control.
Usage | The usage of the control.
Pullup | true/false if the internal pull up resistor should be used.
Debounce | true/false if debounce logic should be used on this input.
Encoded | true/false if the input is encoded. If it is encoded, each input pin represents a binary value, so, for example 3 inputs makes a 3 bit binary number or 8 different inputs.
Outputs | Only required when Encoded is true. Specifies the maximum output value of the control. For example, a control that is decimal encoded will have 4 output pins with a theoretical range of 0-15, but only uses 0-9. Outputs would therefore be 10.

## <Input>

Specifies an input pin of the rotary selector switch.

## Attributes

Bit | Which bit this input represents. Non-coded bits are numbered 1,2,3,4,..., while coded bits are numbered 1,2,4,8,16,...
Port | The I/O pin that this selector bit is connected to. One of PA0..PF7.

##
<LCD>

Specifies an character based LCD device. The microcontroller will implement a HID Alphanumeric Device, with the bare minimum functionality.

### Attributes

Name | Optional descriptive text name.
UsagePage | The usage page of the control.
Usage | The usage of the control.
Rows | The number of rows the LCD can display.
Columns | The number of columns the LCD can display.
Bus8Bit | true/false if the microcontroller should use an 8bit bus (D0..7) or a 4 bit bus (D4..7)
PortRS | The I/O pin that the RS pin of the LCD is connected to. One of PA0..PF7.
PortRW | The I/O pin that the RW pin of the LCD is connected to. One of PA0..PF7.
PortE | The I/O pin that the E pin of the LCD is connected to. One of PA0..PF7. Note, if more than one LCD is defined, this is the only pin that needs to be unique amongst LCDs.
PortD0 | The I/O pin that the D0 pin of the LCD is connected to. One of PA0..PF7. Not used in 4 bit mode.
PortD1 | The I/O pin that the D1 pin of the LCD is connected to. One of PA0..PF7. Not used in 4 bit mode.
PortD2 | The I/O pin that the D2 pin of the LCD is connected to. One of PA0..PF7. Not used in 4 bit mode.
PortD3 | The I/O pin that the D3 pin of the LCD is connected to. One of PA0..PF7. Not used in 4 bit mode.
PortD4 | The I/O pin that the D4 pin of the LCD is connected to. One of PA0..PF7.
PortD5 | The I/O pin that the D5 pin of the LCD is connected to. One of PA0..PF7.
PortD6 | The I/O pin that the D6 pin of the LCD is connected to. One of PA0..PF7.
PortD7 | The I/O pin that the D7 pin of the LCD is connected to. One of PA0..PF7.
Row0 | Specifies the start address of the Row 0. This is to support non-standard character devices. It is normally 0.
Row1 | Specifies the start address of the Row 1. This is to support non-standard character devices. It is normally 64.
Row2 | Specifies the start address of the Row 2. This is to support non-standard character devices. It is normally 20.
Row3 | Specifies the start address of the Row 3. This is to support non-standard character devices. It is normally 84.

##
<LED>

Used to define an LED output. Can also be used to define any 1-bit output.

### Attributes

Name | Optional descriptive text name.
UsagePage | The usage page of the control.
Usage | The usage of the control.
Port | The I/O pin that the LED is connected to. One of PA0..PF7.
Source | true/false if the microcontroller sources/sinks current. (Common cathode/common anode)

##
<BicolourLED>

Used to define a bi-colour LED output. This is a 2-bit, 3 value output.

### Attributes

Name | Optional descriptive text name.
UsagePage | The usage page of the control.
Usage | The usage of the control.
PortA | The I/O pin that LED leg 1 is connected to. One of PA0..PF7.
PortB | The I/O pin that LED leg 2 is connected to. One of PA0..PF7.

##
<RGBLED>

Used to define an RGB LED output. This is a 3-bit, 8 value output.

### Attributes

Name | Optional descriptive text name.
UsagePage | The usage page of the control.
Usage | The usage of the control.
PortR | The I/O pin that the Red LED leg is connected to. One of PA0..PF7.
PortG | The I/O pin that the Green LED leg is connected to. One of PA0..PF7.
PortB | The I/O pin that the Blue LED leg is connected to. One of PA0..PF7.
Source | true/false if the microcontroller sources/sinks current. (Common cathode/common anode)

##
<PWM>

Provides a PWM output on one of the PWM pins.

### Attributes

Name | Optional descriptive text name.
UsagePage | The usage page of the control.
Usage | The usage of the control.
Port | The I/O pin that the PWM signal is output. One of PA0..PF7. (really its more restrictive than that).
Resolution | Specifies counter top for this PWM. This is a bit lazy. This value should be determined from the <Config> tag. Used to specify the HID LogicalMax, and the size of the Output Report value.

##
<Counter>

Specifies a counter. There can only be one counter. It appears as an n-bit HID input.

### Attributes

Name | Optional descriptive text name.
UsagePage | The usage page of the control.
Usage | The usage of the control.
Peroid | Specifies the counting period in ms, from 0 to 0xFFFF
Bits | Specifies the number of bits for the value in the input report.

## Example

This example is of my first CNC pendant.

<!

DOCTYPE GenericHIDDevice>
<GenericHIDDevice>
<Device Manufacturer="FranksWorkshop" PID="1241" Product="Lathe Pendant" VID="7232" SerialNo="00001" Release="100" />
<Configuration Timer2="1,8,100" BusPowered="true" Timer3="1,8,100" PowerPort="" UseStatusLEDs="LED1" is5Volts="true" HIDDebug="false" Interval="50" UsagePage="1" PowerConsumption="275" Usage="1" SerialDebug="false" Timer1="1,8,100" />
<Controls>
<LCD Rows="4" PortE="PA2" Row0="0" Row1="64" Row2="20" Row3="84" UsagePage="20" Columns="20" PortRS="PA0" PortD0="" PortD1="" Name="" PortD2="" PortD3="" PortD4="PA3" PortRW="PA1" Bus8Bit="false" PortD5="PA4" Usage="1" PortD6="PA5" PortD7="PA6" />
<AnalogIn Bits="10" Name="A" UsagePage="1" Usage="50" Port="PF1" />
<AnalogIn Bits="10" Name="Y" UsagePage="1" Usage="50" Port="PF2" />
<AnalogIn Bits="10" Name="X" UsagePage="1" Usage="49" Port="PF3" />
<AnalogIn Bits="10" Name="Z" UsagePage="1" Usage="48" Port="PF0" />
<KeyMatrix Debounce="true" UsageMin="1" UsagePage="9" Pullup="true" >
<RowIn Port="PE4" />
<RowIn Port="PE5" />
<RowIn Port="PE6" />
<RowIn Port="PE7" />
<ColOut Port="PE0" />
<ColOut Port="PE1" />
<ColOut Port="PE2" />
<ColOut Port="PE3" />
<Key Row="0" Name="1" Col="0" />
<Key Row="0" Name="2" Col="1" />
<Key Row="0" Name="3" Col="2" />
<Key Row="0" Name="4" Col="3" />
<Key Row="1" Name="5" Col="0" />
<Key Row="1" Name="6" Col="1" />
<Key Row="1" Name="7" Col="2" />
<Key Row="1" Name="8" Col="3" />
<Key Row="2" Name="9" Col="0" />
<Key Row="2" Name="10" Col="1" />
<Key Row="2" Name="11" Col="2" />
<Key Row="2" Name="12" Col="3" />
<Key Row="3" Name="13" Col="0" />
<Key Row="3" Name="14" Col="1" />
<Key Row="3" Name="15" Col="2" />
<Key Row="3" Name="16" Col="3" />
</KeyMatrix>
<DigitalEncoder Name="JogWheel" UsagePage="1" Usage="65200" PortA="PB0" PortB="PB1" />
<DigitalEncoder Name="FeedOverride" UsagePage="1" Usage="65200" PortA="PB2" PortB="PB3" />
<DigitalEncoder Name="SpindleOverride" UsagePage="1" Usage="65200" PortA="PB4" PortB="PB5" />
<LED Source="true" Name="ChangeTool" UsagePage="8" Usage="1000" Port="PD0" />
<LED Source="true" Name="Run" UsagePage="8" Usage="1001" Port="PD1" />
<RotarySwitch Debounce="true" Encoded="true" Name="AxisSelect" UsagePage="9" Outputs="6" Usage="65200" Pullup="true" >
<Input Bit="1" Port="PC0" />
<Input Bit="2" Port="PC1" />
<Input Bit="4" Port="PC2" />
</RotarySwitch>
<RotarySwitch Debounce="true" Encoded="true" Name="MultiplierSelect" UsagePage="9" Outputs="4" Usage="65200" Pullup="true" >
<Input Bit="1" Port="PC3" />
<Input Bit="2" Port="PC4" />
</RotarySwitch>
<LED Source="true" Name="SingleStep" UsagePage="8" Usage="1002" Port="PC7" />
<Switch Debounce="true" Name="Step Mode" UsagePage="9" Usage="1001" Pullup="true" Port="PC5" />
<Switch Debounce="true" Name="Reset" UsagePage="9" Usage="1001" Pullup="true" Port="PC6" />
</Controls>
</GenericHIDDevice>