Microcontroller Configuration Description (MCD) Files

• Home
• Return to
  Franks Workshop
• Return to
  Sourceforge

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

<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

<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

<AnalogIn>

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

Attributes

<Switch>

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

Attributes

<TricolourLED>

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

Attributes

<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

<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

<ColOut>

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

Attributes

<RowIn>

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

Attributes

<Key>

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

Attributes

<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 Log₂(n)+1 bits are required.  The RotarySwitch tag contains child nodes which identify the input pins, and which bits they refer to.

Attributes

<Input>

Specifies an input pin of the rotary selector switch.

Attributes

<LCD>

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

Attributes

<LED>

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

Attributes

<BicolourLED>

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

Attributes

<RGBLED>

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

Attributes

<PWM>

Provides a PWM output on one of the PWM pins. 

Attributes

<Counter>

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

Attributes

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>