USB Base Custom Hardware Interface for Unity3D

This is a simple project to demonstrate the USB custom hardware interfacing with Unity3D game engine on top of Microsoft Windows operating system(s). The custom hardware unit used in this demo is build around Microchip's PIC18F2550 MCU. This custom USB controller consists of 4 push buttons and a linear potentiometer. In the supplied demo, the user needs to control the aircraft with those buttons and the potentiometer. According to the game logic 4 buttons are used to control the flying direction and flying angle of the aircraft and the potentiometer is used to control the speed of the aircraft.

As illustrated in figure above, the host environment consists of 2 main applications such as Session Controller and Unity3D game. Session Controller is responsible for USB communication and data conversions. It's a native application written using Delphi and it gets started with Unity game project. Communication between Session controller and Unity game project is happening through an OS level shared memory location. In this demo both Session Controller and Unity game project are heavily dependent on Windows API functions, and also both the applications require administrative privileges to execute. In this demo project MCU firmware is developed using MikroC PRO 5.0. Session controller is developed using Embarcadero Delphi XE3 and all the Unity scripts are in C#. HID interface of this project is based around J.W. Beunder's Delphi HID library. The microcontroller firmware consists of a simple port scanner and ADC (Analog to Digital Converter) scanner. When the scanner dectects some change in input, it transmits all the "port values" and "ADC value" to the USB HID buffer. Microcontroller firmware is listed below and it is specially designed for PIC18F2550 MCU, but it can be used with PIC18F2455, PIC18F4455 and PIC18F4550 MCUs with slight modifications.

 #define USB_BUFFER_SIZE 64 #define USB_LINK_SIGNATURE 0x3E #define ADC_NOISE_OFFSET 5 unsigned char usb_readbuff[USB_BUFFER_SIZE] absolute 0x500; unsigned char usb_writebuff[USB_BUFFER_SIZE] absolute 0x540; unsigned char button_buffer = 0x0; unsigned int speed_val, speed_buffer = 0x0; //handle MCU interrupts void interrupt() { USB_Interrupt_Proc(); } //function to clear USB write buffer void clear_write_buffer() { unsigned char wpos; for(wpos = 0; wpos < USB_BUFFER_SIZE; wpos++) usb_writebuff[wpos] = 0x0; usb_writebuff[0] = USB_LINK_SIGNATURE; } void init_system() { clear_write_buffer(); //enable MCU's USB connectivity and init HID module. HID_Enable(&usb_readbuff, &usb_writebuff); ADC_Init(); //setup microcontroller I/O configuration INTCON2 = 0x0; ADCON1 = 0xE; PORTB = 0; TRISB = 0x0F; PORTA = 0; TRISA = 0x1; Delay_ms(10); } //function to write scanned port values and ADC value to USB data buffer void tx_usr_inputs() { usb_writebuff[1] = button_buffer; usb_writebuff[2] = (speed_val & 0xFF); usb_writebuff[3] = (speed_val >> 8); while(!HID_Write(&usb_writebuff, 64)); asm nop; } void main() { init_system(); while(1) { speed_val = ADC_Get_Sample(0); //check for port or ADC value changes if((button_buffer != (PORTB & 0xF)) || (abs(speed_val - speed_buffer) > ADC_NOISE_OFFSET)) { //port or ADC value is changed... button_buffer = (PORTB & 0xF); speed_buffer = speed_val; tx_usr_inputs(); } } }

As described earlier, interface between the game and USB HID peripheral is made using a Delphi application. This application creates named shared memory and writes all the processed data to that space. Because of this techinique multiple game instances can read the USB controller's data and it also reduces the synchronization issues between the game and hardware device. This interface code is listed below:

 unit ufMain; interface uses Winapi.Windows, Winapi.Messages, System.SysUtils, System.Variants, System.Classes, Vcl.Graphics, Vcl.Controls, Vcl.Forms, Vcl.Dialogs, uCommon, HIDctrlIntf, Vcl.ExtCtrls; const USB_CNTLR_VID = $8462; USB_CNTLR_PID = $0004; USB_CNTLR_SIGNATURE_CODE = $3E; SPEED_ADC_MIN = $08C; SPEED_ADC_MAX = $384; type TfrmMain = class(TForm) tmrUSB: TTimer; procedure FormCreate(Sender: TObject); procedure FormDestroy(Sender: TObject); procedure tmrUSBTimer(Sender: TObject); private IsDevInUse: Boolean; IPCPntr: PIPCDataset; MemMapHandler: THandle; USBDevList: THIDdeviceList; procedure InitIPCDataSet(); public procedure InitUSBDeviceScan(); procedure TxHIDData(BtnCode: Byte; ADCInput: Word); end; var frmMain: TfrmMain; ADCSpeedPos: Word; implementation {$R *.dfm} //capture USB library events (including USB attach and deattach events) procedure OnUSBEvent; stdcall; begin TfrmMain(Application.MainForm).InitUSBDeviceScan; end; //function to read data from HID buffer procedure OnHIDRead(Data: THIDbuffer); stdcall; begin if((SizeOf(THIDbuffer) > 3) and (Data[0] = USB_CNTLR_SIGNATURE_CODE)) then begin //recreate 10bit ADC value ADCSpeedPos := Data[2] + (Data[3] shl 8); if(ADCSpeedPos < SPEED_ADC_MIN) then ADCSpeedPos := 0 else ADCSpeedPos := Round(((ADCSpeedPos - SPEED_ADC_MIN)/SPEED_ADC_MAX) * 100); TfrmMain(Application.MainForm).TxHIDData((not Data[1]) and $0F, ADCSpeedPos); end; end; //module's init point procedure TfrmMain.FormCreate(Sender: TObject); begin try USBsetEventHandler(@OnUSBEvent); HIDsetEventHandler(@OnHIDRead); IsDevInUse := false; //create shared memory space MemMapHandler := CreateFileMapping(INVALID_HANDLE_VALUE, nil, PAGE_READWRITE, 0, $100, COMLINK_NAME); Win32Check(MemMapHandler > 0); IPCPntr := MapViewOfFile(MemMapHandler, FILE_MAP_ALL_ACCESS, 0, 0, $100); Win32Check(Assigned(IPCPntr)); InitIPCDataSet(); //check for USB game controller... InitUSBDeviceScan; except MessageBox(0, 'Unable to create shared memory to initiate the communication link'#10#10'Is this application running with administrative privileges?', Pchar(Application.Title), MB_OK + MB_ICONHAND); if(MemMapHandler > 0) then CloseHandle(MemMapHandler); Application.Terminate; end; end; procedure TfrmMain.FormDestroy(Sender: TObject); begin if(MemMapHandler > 0) then CloseHandle(MemMapHandler); end; procedure TfrmMain.InitIPCDataSet(); begin IPCPntr^.SignatureCode := COMLINK_SIGNATURE; TxHIDData(0, 0); end; procedure TfrmMain.TxHIDData(BtnCode: Byte; ADCInput: Word); begin if(MemMapHandler > 0) then begin IPCPntr^.ControlInputs := BtnCode; IPCPntr^.SpeedInput := ADCInput; end; end; procedure TfrmMain.InitUSBDeviceScan(); var USBDevCount : Byte; begin //Searching for USB game controller... HIDscanForDevices(USBDevList, USBDevCount, USB_CNTLR_VID, USB_CNTLR_PID); if((USBDevCount > 0) and (not IsDevInUse)) then tmrUSB.Enabled := true else begin try HIDcloseDevice(USBDevList[0]); finally IsDevInUse := false; end; end; end; //timer module is used to avoid multipal high frequency USB events procedure TfrmMain.tmrUSBTimer(Sender: TObject); begin tmrUSB.Enabled := false; IsDevInUse := HIDopenDevice(USBDevList[0]); end; end.

In Unity, the above mentioned shared memory is accessed using the same Windows API functions and its implementation is available in the UHWComLink.cs file. GetHIDControlData is the function to get all the shared memory data and it's listed below:

 public bool GetHIDControlData(out UHWComData ComDataSet) { ComDataSet.SignatureCode = 0; ComDataSet.ControlInputs = 0; ComDataSet.SpeedControl = 0; ShMemFileHandler = OpenFileMapping(FileRights.AllAccess, false, COMLINK_NAME); if (ShMemFileHandler == IntPtr.Zero) return false; IPCMapPntr = MapViewOfFile(ShMemFileHandler, FileRights.AllAccess, 0, 0, 0x100); if (IPCMapPntr == IntPtr.Zero) return false; //read values from shared data structure ComDataSet.SignatureCode = Marshal.ReadByte(IPCMapPntr); ComDataSet.ControlInputs = Marshal.ReadByte(IPCMapPntr, 1); ComDataSet.SpeedControl = Marshal.ReadInt16(IPCMapPntr, 2); CloseHandle(ShMemFileHandler); return true; }

A schematic of the USB game controller is illustrated in the next figure. This can be constructed using breadboard, stripboard or PCB (Printed Circuit Board). Recommended platform to build this controller is a PCB and the complete PCB design pattern is available at the project repository.

The supplied PCB design of this project is based on commonly-available SMD components. Please note that this hardware setup is quite sensitive to external noises, so it is recommended to use some properly-grounded shield with this controller. If the USB connection between the host and the controller is more than 1.5m, it is advisable to use a USB cable with ferrite bead(s). All the source code and design documents of this project are available to download at github.com/dilshan/unityusb. A demonstration video of the prototyped system can be viewed