mikael svensson - um) - u

Fusing Reality with theVirtual Reality of a Serious

Game

Mikael Svensson

November 4, 2010Master’s Thesis in Computing Science, 30 credits

Supervisor at BAE Systems Hagglunds: Johan PerssonSupervisor at CS-UmU: Jonny Pettersson

Examiner: Fredrik Georgsson

Umea UniversityDepartment of Computing Science

SE-901 87 UMEASWEDEN

Abstract

Real world military and civilian training causes hundreds of lethal accidents each yeararound the world. Until now the reality has been impossible to replace in civilian andmilitary training. But with the emergence of serious games combined with the latestadvances in 3d simulated environments Bohemia Interactive developed the COTS (Com-mercially Of The Shelf) game VBS2(Virtual BattleSpace 2). BAE Systems Hagglunds’goal with this thesis is to investigate the potential of using VBS2 as the simulationplatform in a new cost effective and realistic vehicle training systems.

The major focus of this thesis is to find a way to control vehicles in VBS2. Afterevaluating the tools available during this thesis project DSF (Device Simulation Frame-work) is chosen to control VBS2. DSF is used to solve the problem by simulating a USBHID Joystick which controls VBS2 through DirectInput. This thesis therefore containsan in-depth study of the USB2.0 protocol, the HID protocol, and the DSF framework.The thesis shows in the end a prototype that can control VBS2 or any other game thatsupports DirectInput. The thesis also reveals a general design of the core of the vehicletrainer that connects the hardware simulator SimBas with VBS2.

Contents

1 Introduction 1

1.1 BAE Systems Hagglunds . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

1.2 Background . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

1.3 Systems today . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

1.4 VBS2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

1.5 BAE Systems Hagglunds Goal . . . . . . . . . . . . . . . . . . . . . . . 2

1.6 Outline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

2 Problem Areas 3

2.1 The design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

2.2 The interaction with VBS2 . . . . . . . . . . . . . . . . . . . . . . . . . 4

2.3 The implementation of the most important part of the system . . . . . . 4

3 How To Control VBS2 5

3.1 Fusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

3.2 DirectInput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

3.3 Comparison . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

4 DirectInput and the underlaying driver stack 7

4.1 DirectInput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

4.2 Windows Driver stack . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

4.3 Driver layers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

4.4 The driver stack below DirectInput . . . . . . . . . . . . . . . . . . . . . 10

5 Simulation of a Joystick in Windows 13

5.1 Device Simulation Framework . . . . . . . . . . . . . . . . . . . . . . . . 14

5.1.1 The DSF COM object model . . . . . . . . . . . . . . . . . . . . 15

5.1.2 USB2.0 Descriptors . . . . . . . . . . . . . . . . . . . . . . . . . 17

5.1.3 Descriptor objects in SoftUSBDevice . . . . . . . . . . . . . . . . 20

5.1.4 HID Descriptors . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

5.1.5 Report Descriptors . . . . . . . . . . . . . . . . . . . . . . . . . . 21

5.1.6 The Report and DSF . . . . . . . . . . . . . . . . . . . . . . . . 26

iii

iv CONTENTS

6 Design and Implementation 27

6.1 Design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

6.1.1 The hardware . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

6.1.2 The software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

6.2 Implementation of Simulated Joystick . . . . . . . . . . . . . . . . . . . 29

6.2.1 Initiation & Configuration . . . . . . . . . . . . . . . . . . . . . . 31

6.2.2 Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

6.2.3 Plug in and Unplug the device . . . . . . . . . . . . . . . . . . . 33

6.2.4 Sending reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

6.2.5 Termination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

6.2.6 C#/.net - C++/com wrapper . . . . . . . . . . . . . . . . . . . . 34

7 Results and Conclusions 35

7.1 Discussion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

7.2 Future work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

8 Acknowledgements 39

References 41

A Requirements 45

A.1 User Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

A.2 System Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

List of Figures

4.1 Figure of the general driver stack composed with knowledge from Mi-

crosoft MSDN. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

4.2 A conceptual image of the driverstack under DirectInput composed with

knowledge from Microsoft MSDN. . . . . . . . . . . . . . . . . . . . . . 11

5.1 A combined image of the driverstack under DirectInput and the DSF

architecture composed with knowledge from Microsoft MSDN. . . . . . 15

5.2 An image of the DSF object hierarchy composed with knowledge from

Microsoft MSDN. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

5.3 An image of the USB2.0 descriptors composed with knowledge from Mi-

crosoft msdn and the USB2.0 specification. . . . . . . . . . . . . . . . . 17

5.4 An image of a report descriptor that describe a HID Joystick.The fig-

ure is composed with knowledge from HID class specification,the USB2.0

specification, and HID usage tables specification. . . . . . . . . . . . . . 22

6.1 A conceptual image of the system. . . . . . . . . . . . . . . . . . . . . . 28

6.2 The state chart for the simulated HID device. . . . . . . . . . . . . . . . 30

7.1 A screenshot in Windows showing the prototype just after it have moved

the simulated joystick. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

v

vi LIST OF FIGURES

List of Tables

5.1 Table over items in figure 5.4. . . . . . . . . . . . . . . . . . . . . . . . . 23

5.2 Table over the attribute field of the input item. . . . . . . . . . . . . . . 24

6.1 Table over the objects that is initiated. . . . . . . . . . . . . . . . . . . . 31

vii

viii LIST OF TABLES

Chapter 1

Introduction

This master thesis was done at BAE Systems Hagglunds head quarters in Ornskoldsvikas a thesis for the degree of Master in computing science and engineering at UmeaUniversity. The thesis work started of as an investigation in how to solve the problemof making cheaper and better training simulators for BAE Systems Hagglunds differentVehicles. This by using COTS(commercially off the shelf) games and more specificthe military simulation game VBS2(Virtual Battle Space 2). As the work proceededdifferent problem areas were identified and the work ended in this Master thesis whichproposes solutions in the different problem areas.

1.1 BAE Systems Hagglunds

BAE System Hagglunds is a division in the global company BAE that has about 107000 employees all over the world. BAE Systems Hagglunds has about 950 employeesin different areas from production to development. BAE Systems Hagglunds develops,manufactures and modifies military vehicles ranging from all-terrain vehicles to combatvehicles. BAE Systems Hagglunds has developed and manufactured many well knownvehicles like CV90, BV206, Bv206s, BVS10, and SEP. BAE Systems Hagglunds hasalso an impressive industry history in making wooden furniture, buses, electric engines,trams, airplanes, and several other products.[1]

1.2 Background

The customers of BAE Systems Hagglunds often ask for a more cost-effective alternativefor training in a virtual environment. VBS2(see section 1.4) could be a solution to thatrequest. VBS2 is the market leading serious game in the category of military simulationtoday and is a further development from Operation flashpoint game idea by BohemiaInteractive Australia [6]. VBS2 might be interesting as a virtual environment and as aplatform for future training systems from BAE System Hagglunds.

1.3 Systems today

The current training systems are made ”in house” with expensive third party 3d engines.These systems are very expensive to develop and maintain. They can not compete with

1

2 Chapter 1. Introduction

the COTS games that does develop more and better functions faster.

1.4 VBS2

VBS2 is a serious game and an battlefield simulator. Serious games is a category of gamesthat focuses on education for a real world subject like military tactics, health care, andfirefighting [35]. Serious games have a pedagogical part that is incorporated into thegame. One of the pedagogical parts in VBS2 is AAR(after action review). AAR recordsthe training session in VBS2 and can replay the recording after the training session. Theinstructor can show exactly what happened and give advice on improvements. Anotherdifference between normal games and Serious games like VBS2 is that normal gamestries to enhance the game to be more entertaining and discard human drawbacks that iscalled the super soldier syndrome [29]. VBS2 on the other hand tries to mimic humancapability and drawbacks. One of the futures of VBS2 is that it simulates the human eyeslight sensitivity. When you remove the night vision goggles the eyes have to acclimatizeto the dark which gives a more realistic night combat situations. VBS2 also has ballisticsimulation that they claim is 99% realistic [2]. Their ballistic simulation uses correctparameters down to the rotation of earth which enables realistic weapons training. VBS2is highly customizable to be able to simulate different real world areas and real worldobjects. VBS2 has been a real success story for Bohemia Interactive Australia and isnow market leading. They have attracted several important users, for example NATO,USA, Australia and the Netherlands. Over all, this makes VBS2 a good candidate assimulation platform for new vehicle training systems.

1.5 BAE Systems Hagglunds Goal

The goal of BAE Systems Hagglunds with this thesis work is to investigate if it is possibleto build a vehicle training system with VBS2 as the simulation platform. The differentparts of the goal are to find a way to interact with VBS2, to design a prototype system,and to implement the most important parts of the system.

1.6 Outline

This thesis is divided into eight chapters which are followed by one appendix. Thischapter gives an introduction and background to the thesis. The chapter also states thegoal for the thesis. Chapter two describes the problems that are identified in the pilotstudy. Chapter three investigate and discuss the two ways to control VBS2 which lead tothe decision to use DirectInput. Chapter four investigates the underlying architecture ofDirektInput which includes windows driver stack, USB, and HID. Chapter five discusseshow to use DSF to simulate a Joystick. Chapter five goes on and describes USB and HIDdeeper and how DSF simulates the joystick. Chapter six describe first the general designof the vehicle training system and after that the chapter describes how the simulatedJoystick prototype is implemented. Chapter seven discusses the result and present whatshould be done in the future. Chapter eight is acknowledgments and after chapter eightfollows the references. Appendix A contains the requirement document.

Chapter 2

Problem Areas

Chapter one describes the goals of this thesis and this chapter will explain the problemsthat needs to be solved to best satisfy the goals. This chapter is also largely the resultof the pilot study done in the beginning of the thesis work.

The assignment is to investigate if it is possible to build a vehicle training system withVBS2 as the simulation environment. The parts of the assignment are to find a way tocontrol VBS2 from another application, make a design on a general vehicle trainer, andimplement the most important parts of the system.

2.1 The design

A general vehicle training system must be designed to handle multiple roles. A combatvehicle has for example; a driver, a gunner, and a commander. The task of the com-mander is to find targets, to navigate, and to give orders. The task of the gunner is toeliminate targets, to steer the turret, and to choose weapons. The task of the driver isto drive the vehicle and to control all the functions of the chassis. The system has tobe designed to be easy to change and to create new roles, because various vehicles mayhave different roles. The design has to involve a connection to the hardware throughSimBas. SimBas is a modular simulation of hardware and software of all the differentelectronic components in a vehicle from BAE Systems Hagglunds. Real hardware canalso be connected to SimBas to replace the simulated counterparts. The interactionwith VBS2 shall be tested with a prototype. The full list of requirements can be foundin appendix A.

3

4 Chapter 2. Problem Areas

2.2 The interaction with VBS2

The most important part of the system is the connection to VBS2. Other parts of thesystem will be useless without the ability to control VBS2. The goal is to be able to steerthe vehicles in VBS2 as it would be in real life. There are two standard ways to controlVBS2. The first one is through DirectInput, that is an API (Application ProgrammingInterface) for developers to collect user inputs from keyboards, mouses, joysticks, andother game controllers [11]. The other one is VBS2’s API FUSION that enables otherprograms to interact with VBS2. A literature study has to be done in order to decidewhich way that would be the best to chose for different problems. The way that isselected will then have to be studied closer in a deeper literature study. The knowledgegained in the literature studies will also be used when implementing the prototype.

2.3 The implementation of the most important partof the system

As described in the section above the interaction with VBS2 is the most important part ofthe system. The interaction with VBS2 is also the part where BAE System Hagglundswill gain the most knowledge if implemented. The other parts of the system will beimplemented if time allows. To ease the maintenance the system has to be implementedin C# mostly. The language used with the interaction with VBS2 is depending of theresult of the literature study.

Chapter 3

How To Control VBS2

Chapter 2 states that there are two ways to control VBS2, with Fusion and/or Direct-Input. This chapter will discuss these two ways and show which one of them is the bestto use in this system.

3.1 Fusion

Fusion is an API built by SimCentric which is an add-on module to VBS2 [30]. Thepurpose of Fusion is to enable developers to control VBS2 from outside of the simulation.The Fusion API is a collection of C++ classes that enables developers to create, modify,and get information from objects in VBS2. Fusion is released in stages, v1.0 released inMay 2009 and v2.0 in April 2010 [7].

In v1.0 Fusion is abstracting the ASI (Application Script Interface) to the C++ APIwhich is object oriented and easier to use. The purpose of the ASI’s is to create andmodify entire scenarios or parts of scenarios in VBS2. The ASI has no direct controlof the models in VBS2. In v2.0 SimCentric enables the developers to use the simula-tion core, which means that developers will have complete control over the models andenvironment in VBS2.[30]

3.2 DirectInput

DirectInput is an Microsoft API which enables developers to gather inputs from differentinput devices without knowing the properties of the device beforehand. DirectInput alsohandles output for force feedback and haptic devices. When a developer needs inputfrom a joystick they uses DirectInput to enumerate all attached devices to the computer.The Developer can then choose which joystick to use and fetch the capabilities of thatjoystick. The joystick describes itself in a standardized way which enables a developerto develop applications that are compatible with a wide range of input devices.[12]

VBS2, as almost all other windows games supports DirectInput which are a widelyused industry standard for input devices. DirectInput is incorporated in the originaluser interface of VBS2 which is an FPS (First Person Shooter) where you play a soldierin first person. The soldier in a vehicle in the game can have different roles. DirectInput

5

6 Chapter 3. How To Control VBS2

is limited by that role and can only do the actions that the role handles. For examplea person in the game that plays the role of a driver can steer, accelerate, brake, andcontrol lights. A combat vehicle has at least three roles; driver, commander, and gunnerwhich have to be controlled in three separate instances of the game to have full controlof the vehicle.

3.3 Comparison

Fusion and DirectInput are both clearly a way to control VBS2 but they have differentapproaches. DirectInput has a couple of advantages and disadvantages. DirectInput isan industry standard which means that a solution based on DirectInput will work withother games seamlessly. DirectInput will have good support in many years in the futureand if that changes Microsoft will have a long transition period. One of DirectInputdisadvantages is that it needs to have one VBS2 client per role in a vehicle, three tocontrol a combat vehicle. The Game’s DirectInput interface can only use the predefinedactions in the game. The predefined action covers almost all the needed actions exceptfor example fire smokescreen which have to be chosen in a graphical list in the game.

When looking at Fusion’s disadvantages and advantages we have to take in to accountthe different versions. This because the differences between v1.0 and v2.0 are too big.Version 1.0 of Fusion is a powerful tool to modify scenarios in runtime. It has somefunctions to change a vehicles course but it either commands the AI in the game to turnor rotate the vehicle immediately without simulation. There is no good way to realisti-cally steer a vehicle in v1.0 [25]. Version 2.0 will include better functions to steer thevehicle according to information released at this point. Version 2.0 will make it possibleto simulate the dynamics of the vehicle outside VBS2. This will make vehicles in VBS2to behave more realistically. It’s a pity that v2.0 will be released in the end or afterthis project is finished which makes v2.0 not a feasible way to control VBS2 in this thesis.

The conclusion is that Fusion will not be a viable way to control VBS2 until v2.0 isreleased. DirectInput is therefore the best way to control VBS2 in this project.

Chapter 4

DirectInput and theunderlaying driver stack

The previous chapter showed that DirectInput is the currently best way to control VBS2in the time frame of this thesis. The purpose for this chapter is to study the possibilitiesto use DirectInput to control VBS2 without a physical joystick. This will be done bya deeper study in the design of the Windows driver stack and the specific drive stackthat DirectInput uses. This to give a better understanding where and how to insert thesimulated joystick in a way that it can fool the system in perceiving it as a physicaljoystick. Last in this chapter the chosen solution will be studied in closer detail.

4.1 DirectInput

As the previous chapter explained DirectInput is an API that developers use to abstractthe underlying complexity of which and how the attached input devices are connectedand used. The developer do not need to know which type of joystick it is or whichport it is connected to beforehand. There is no purpose to study the DirectInput APIany closer, because developers of applications that use DirectInput will take care ofthe connection between the API and the application. The interesting part is what willhappen under DirectInput where it may be possible to connect a simulated joystick.Under DirectInput is the driver stack which is different depending on which version ofWindows is used. After Windows XP the driver stack has nearly stayed the same. Thescope of this thesis is therefore Windows XP and later. DirectInput is part of DirectXwhich in this thesis is version 5 or later.

4.2 Windows Driver stack

The basics of Windows driver stack is the first step to understand the DirectInput driverstack. The driver stack describes how applications access and use hardware in a stan-dardized way. In this way you could change hardware and the applications will stillwork. This is done in the driver stack HAL (Hardware Abstraction Layer) which hidesspecific hardware from the above layer. The driver stack is divided into two parts, thekernel-mode and the user-mode.

7

8 Chapter 4. DirectInput and the underlaying driver stack

Kernel-mode contains the HAL and routines for memory management, I/O and so on.Kernel-mode code has access to memory and hardware directly. It is running in so calledprivileged processor mode. Privileged processor mode does not have any restriction tothe hardware and can access all memory. The kernel-mode does have some drawbacks.It has not unlimited memory like user-mode which has virtual memory that is also storedon disk. The kernel-mode has also almost no safeguards to protect the memory fromcorruption. Debugging is also more difficult than in user-mode.[24]

User-mode contains applications and user-mode drivers. User-mode applications anddrivers have to go through the Win32 API to access any hardware. Win32 API workslike a gate to the kernel. The user mode application calls the Win32 API and Win32API calls the right kernel-mode function [27].

4.3 Driver layers

The driver stack can be described as a layered structure with each layer adding valueto that device. See the conceptual figure 4.1 that describe the driver stack layers. Thelowest layer is a hardware bus driver that handles a specific bus like USB or Firewire.The bus driver is usually written by Microsoft and is part of the operating system. TheBus driver enumerates devices that are attached on the bus. Under the enumeration itidentifies the devices and creates a device object for each device. [25, 8]

A device object is a representation of that device and contains pointers to the nextdriver object. In this way is the driver stack chained together. Each driver (not minidrivers attached to a class driver) has to create a device object. More information on de-vice objects and driver stacks can be found in the documentation of the WDK(Windowsdriver kit).[9]

The layer above the bus driver is a pair of drivers, the port driver and a miniportdriver. The miniport driver is often developed by the manufacturer of the hardware.The miniport driver handles all the protocol specific requests between the bus driverand the port driver. For example the USB stack has three miniport drivers that eachsupports different version of the USB standard [28]. The port driver or in some caseslike USB is called a host controller handles more generic request about the bus and isnot aware of the version specific details of the bus. In this way newer and better versionsof the protocol and hardware can be added without rewriting the whole stack. The onlything that needs to be rewritten is the miniport driver. The port driver is almost alwayssupplied by the operation system.[25]

The class and miniclass driver pair is built up in a similar way. The class driver han-dles a specific class of devices that is attached on the underlying bus or port. The classdriver is hardware independent which means that the class driver can be reused on otherbuses or ports that have devices of the same class. The class driver is almost alwayssupplied with the operation system. The miniclass driver is the only thing that has tobe rewritten when the underlying bus or port is changed. The miniclass driver is oftensupplied by the manufacturer. Every layer above the class driver in the stack does notknow whats is under the class driver layer and do not need to know. The layers aboveonly wants to know what type of class the device is to be able to use it.[25]

4.3. Driver layers 9

The kernel-mode client drivers handles request from the Win32 API or from a classdriver below. The kernel-mode client driver handles tasks that can’t be done in usermode. The user-mode client driver works similar to the kernel-mode client driver butit is in user-mode. It handles requests from the Win32 API or from applications. User-mode client drivers are preferred because they are easier to develop and do not affectstability of the system as sever as kernel-mode client drivers. This conceptual modelof the driver stack is the basic way to represent a general driver stack in Windows ina simpler way. In most cases not all layers are needed depending on what the purposeof the stack is. Some driver stacks may break the stack concept and have componentoutside the main stack that it calls. One other component not represented in the figureis the filter driver. The filter driver can be placed between every layer to filter outinformation or adding information.[25]

Hardware Bus

Driver

Miniport Driver

Port Driver

Miniclass Driver

Kernel-Mode

Client Driver

User-mode

Kernel-mode

Win32 APIUser-Mode

Client Driver

Application

Class Driver

Figure 4.1: Figure of the general driver stack composed with knowledge from MicrosoftMSDN.


4.4 The driver stack below DirectInput

DirectInput driver stack follows the general conceptual design that is described in thesection 4.3. The figure 4.2 is a conceptual image of the driver stack below DirectInputwith a joystick connected.

In the bottom is the USB bus hardware which follows specified versions of a USB stan-dard. There are two versions of the USB standard used today 2.0 and 1.1.

Version 2.0 is used in situations when higher bandwidth is a priority. Version 1.1 isused in simpler devices like mouses and keyboards. There is also a 3.0 version but ithas just been released and have not yet become a major standard yet. 3.0 has an evenhigher bandwidth than 2.0.[28, 34]

There are three standard protocols for hardware host controller chips that is widelyused today Openhci (Open host controller interface), Uhci (Universal host controllerinterface), and Ehci (Enhanced Host controller interface). Openhci and Uhci are twodifferent host controller interfaces for USB 1.1, both are developed for each their hard-ware specification. There are two groups of hardware and software companies behindthe two standards. Intel created Uhci and all Intel’s USB 1.1 controller chips uses Uhci.Openhci started as an collaboration between Microsoft, Compaq , and National semicon-ductors. Openhci and Uhci both support low-speed and full-speed bandwidth standardsstated in the USB 1.1 specification. This means that when there is an USB 1.1 hostcontroller that Intel have constructed attached to the computer, the computer needs anUhci driver and vice versa. When USB implementers forum started to develop USB2.0they insisted to have only one Host controller interface standard. The name of USB2.0Host controller is Ehci. Ehci takes care of all devices that is USB2.0 compatible anduses high-speed bandwidth standard. Backwards compatibility is ensured by using Uhciand Openhci as companion driver which handles the low-speed and full-speed devices.This means that it is possible to have up to three different host controller drivers at thesame time running in the same computer.[28, 3, 4, 34, 5]

These three drivers can also be called miniport drivers and are paired to the USBhost controller driver also called port driver. USB host controller driver takes care ofall hardware independent tasks. USB host controller driver is developed by Microsoft.Every USB host controller has one USB root hub that contains all the ports that USBdevices can be attached to. The USB devices that are attached to the hub belongs toone of the predefined USB classes. The supported classes are Hub device, HID (HumanInput Devices), mass storage, audio, communication device, printer, content security,and image device -class. In this case the device is a Joystick which conforms to the HIDdevice class. HID is a protocol for input devices of different configurations. Later inthis thesis HID protocol will be discussed further.[28, 13]

Above the USB root hub driver is the HID USB miniclass driver. It handles all theUSB specific tasks for the HID class driver that is on top of the HID USB miniclassdriver. HID protocol can be used on other buses and ports if there is a miniclass driverthat takes care of that bus or ports specific protocol. The HID Class driver and HIDUSB miniclass driver is Developed by Microsoft.[28, 26]

4.4. The driver stack below DirectInput 11

After the HID class driver is the transition to user-mode. In user-mode is DirectIn-put that is dynamically linked to HID.dll. HID.dll is a user-mode client driver thathelps DirectInput to parse the information from the device.[20]

USB Minidriver USB Minidriver USB MinidriverOpenhci Uhci Ehci

USB bus Hardware

USB Host

controller

driver

USB 2.0USB 1.1USB 1.1

USB root hub

HID USB

Miniclass driver

HID

Class driver

User-mode

Kernel-mode

DirectInput HID.dll

Application

using DirectInput

Figure 4.2: A conceptual image of the driverstack under DirectInput composed withknowledge from Microsoft MSDN.

Chapter 5

Simulation of a Joystick inWindows

The knowledge presented in the chapter about DirectInput’s underlying driver stackenables some conclusions to arise about how the solution will look like. One conclusionis that the driver stack under DirectInput, especially the kernel-mode part has to bepart of the solution.

If a solution is made in only user-mode by replacing HID.dll or put a filter betweenWin32 and DirectInput it will generate more problems than it is worth. This is mostlybecause it is not well documented and may affect the stability of other parts of thesystem. If it is possible to find the unofficial interface that is used between DirectInputand HID.dll it may not be safe to use it. Microsoft will for example not inform publiclyif they change an unofficial interface and the change may have unknown consequences.Therefore it is dangerous to use unofficial interfaces.

Microsoft has an official API to emulate mouse and keyboard messages in user modebut not for Joysticks and other HID devices. This is why the driver stack has to be inthe solution. As described in chapter four, some parts of the stack can be changed with-out the layers above recognizing any difference. It is possible to remove the HID USBminiclass driver and replace it with another that receives events from an application inuser-mode. This is a valid solution but is very hard to implement because it involveskernel-mode.

In this thesis time frame it is not possible to learn how to implement a driver thatfollows both the USB specification and the HID specification. The same goes if a filterdriver is used. Another argument is that such a driver will affect the stability of thesystem if it is not built correctly. Microsoft has developed a framework that solves thisproblem in the same way as described above by just removing everything under theUSB Hub driver and replace it with a simulated counterpart [14]. This framework iscalled DSF (Device Simulation Framework). DSF is the technique which is chosen inthis thesis to solve the problem with controlling VBS2, this by implementing a simulatedjoystick.

13

14 Chapter 5. Simulation of a Joystick in Windows

5.1 Device Simulation Framework

DSF is developed to ease the testing of USB devices software before the hardware isbuilt. This helps USB device developers to develop hardware and software in parallel.It enables developers to create a simulation of a USB device and then to control it inuser-mode via an application or a script. DSF is part of WDK and is divided in twoparts, DSF runtime and DSF Interfaces. DSF Runtime installs all the drivers and theresources to run a simulated USB device. It also installs a Software enumerator and autility program which enables adding or removing simulated Ehci controllers from thesystem. DSF interfaces installs the Managed DSF framework. The manged frameworkenables users to develop test applications in .net. But the framework can not create ormodify simulated USB devices it can only use them.[10, 23]

Figure 5.1 shows the conceptual model of a system with simulated HID device usingthe DSF framework. On the right side in figure 5.1 is the driver stack under DirectIn-put that has been described in figure 4.2. The big difference compare to figure 4.2 isthat DSF has replaced the Ehci controller with its own simulated Ehci controller. Thesimulated Ehci controller act as an real Ehci Controller but instead of being connectedto the hardware it is connected to the DSF runtime and the simulated USB device.The simulated Ehci controller has its own mini driver and port driver which has theirhardware access calls re-routed to DSF own libraries in order to simulate for exam-ple interrupts. The DSF mini driver communicates with the simulated Ehci controlleras if it would be a real hardware controller. No layer from and above the mini drivercan see any difference between a hardware controller and the simulated controller.[14, 16]

On the left side of figure 5.1 is the DSF stack. On the top of the stack is the sim-ulated USB device DLL (Dynamic link library) which is implemented by the user ofthe framework. The simulated USB device is developed in User-mode and has to beimplemented in a programming language which supports describing in COM (MicrosoftComponent Object Model) client code. This is because the DSF framework is devel-oped by using that standard. The simulated USB device initiates a SoftUSBDeviceCOM object which is a representation of a USB device. The SoftUSBDevice COMobject is built up very similar to the USB2.0 specification and are the basis for all sim-ulated USB devices. The SoftUSBDevice COM object will later be examine closer. TheSoftUSBDevice COM object is connected to it’s counterpart SoftUSBDevice object inKernel-mode. The SoftUSBDevice object in kernel-mode is plugged in to the simulatedEhci controller with the help of DSF Runtime. More on that later. The COM objectis then used to handle all USB transactions which transmits configurations and reportsto the simulated Ehci controller which passes on the information up in the DirectInputdriver stack. In the bottom of the DSF stack is the DSF runtime. The runtime is builtto handle a variety of simulated devices and buses. But with existing release it can onlyhandle simulated USB buses.[14, 15]

5.1. Device Simulation Framework 15

DSF USB

MinidriverEhci

DSF USB Host

controller

driver

USB 2.0

USB root hub

HID USB

Miniclass driver

HID

Class driver

User-mode

Kernel-mode

DirectInput HID.dll

Application

using DirectInput

Application

that uses the simulated

USB Device

Simulated USB

Device DLL

SoftUSBDevice

Object

DSF Runtime

Simulated USB

Ehci Controller

SoftHIDProtocolXlator

Object

DSF Framework

HID

US

B D

rive

r Sta

ck

DS

F S

tack

Figure 5.1: A combined image of the driverstack under DirectInput and the DSF archi-tecture composed with knowledge from Microsoft MSDN.

5.1.1 The DSF COM object model

The core of the DSF COM object model is based on three COM objects DSF, DSFDe-vice, and DSFBus with respective interfaces IDSF, IDSFDevice, and IDSFBus. TheDSF runtime is represented in the framework with the DSF COM object. DSF COMobject is the root object in the hierarchy and may contain children devices of the objecttype DSFDevices. DSFDevices may also have children devices if it satisfies IDSFBusinterface. Every device in the DSF framework has to satisfy the IDSFDevice interfacein order to be added to the hierarchy. The hierarchy is built up in this way which isshown in figure 5.2. The DSF root object has several methods and properties. One ofthe properties is the children devices which is a collection of DSFDevices. The collectionhas its own object type DSFDevices which have only methods to read the collection.It has unfortunately a name that can be mixed up with DSFDevice in plural. Fromhere on DSFDevices means DSFDevice in plural. DSF have several methods but themost important method is HotPlug. HotPlug is used to attach an IDSFDevice to thehierarchy. HotPlug can only attach a DSFDevice to an DSFDevice that also satisfies


IDSFBus interface. This is why DSFDevices may only have children if it also satisfiesIDSFBus interface. When HotPlug is called to attach a IDSFDevice to a IDSFBus, forexample to the simulated Ehci controller, it will notify the simulated Ehci controllerthrough the DSF runtime that a new device has been attached. The simulated Ehcicontroller simulates a hardware interrupt to the DSF USB Ehci mini driver which actslike it is a real hardware device that has been attached. The IDSFBus have only twomethods HotPlug and Unplug. HotPlug works in the same way as IDSF HotPlug withthe difference that IDSF HotPlug returns the IDSFBus which the simulated device isplugged in to. This because IDSF do not have an Unplug method. The DSF COMobject model contains several more types of objects which can be read about in theWDK documentation. [15, 14, 22]

IDSF

IDSFDevice

IDSFDevice

IDSFDevice

IDSFBus

IDSFDevice

Figure 5.2: An image of the DSF object hierarchy composed with knowledge fromMicrosoft MSDN.

SoftUSBDevice is an USB device simulator and follows the DSF object model de-scribed earlier. SoftUSBDevice has a property which returns the SoftUSBDevice ownDSFDevice object which then is used to HotPlug to ether the simulated Ehci controlleror a SoftUSBHub. SoftUSBDevice is designed to follow the USB2.0 specification toenable it to be perceive as an real USB device. The USB2.0 specification specifies thatdescriptors shall describe the device to the host computer. These descriptors containsall the properties of that device from its power needs to how the data pipeline shall beset up. SoftUSBDevice is one of those descriptor representations. SoftUSBDevice andthe other descriptor representations have two sides here, they are both a representationof the descriptor and part of the logic behind the simulated USB device.


SoftUSBDevice

SoftUSBConfiguration SoftUSBConfiguration

SoftUSBInterface SoftUSBInterfaceSoftUSBInterface

SoftUSBEndpoint SoftUSBEndpoint

SoftUSBEndpoint SoftUSBEndpoint

Figure 5.3: An image of the USB2.0 descriptors composed with knowledge from Mi-crosoft msdn and the USB2.0 specification.

5.1.2 USB2.0 Descriptors

The format of the descriptors is well defined in the USB2.0 specification but only thebasic structure and important property will be described in this thesis. The structureof the descriptor can be described as a tree with four levels which can be seen in figure5.3. Each level contains one type of descriptor. These types are device, configuration,interface, and endpoint. There are three more descriptors other speed configuration anddevice qualifier descriptors which is used when a high-speed capable USB2.0 device needsto run in full-speed or low-speed. device qualifier is similar to the device descriptor butdo only contain the information needed the change the speed. other speed configurationis identical to the configuration descriptor. The full-speed and low-speed configurationswill not be described here. The third descriptor is the string descriptor that contains allstrings that describes the device in human readable text. All descriptors have 2 fieldsin common which is the length of the descriptor and the type of the descriptor which isidentified by a number.[34]

Device descriptor

The root level of the descriptor tree contain one device descriptor which contain generalinformation about the device. The important properties are USB specification version,device class, device protocol, string descriptors, id fields, and number of configurationdescriptors. The property of the USB specification version number informs the hostcomputer which version of the specification the descriptors will follow.[34]

Device class and device subclass property is set to the class of which this device belongsto. Examples of classes are HID and audio devices, these classes have been described insection 4.4. If this property is set to zero the class of the device is set in each interface.Device protocol work in the same way if set to zero. Device protocol is used to specifywhich protocol that should be used. For example a USB hub device can have two dif-ferent protocols named single TT or multi TT. Both class and protocol definition aredefined by USB Implementers Forum. [34]

The Device descriptor has three types of string descriptors index properties that can beset, Manufacturer, serial number, and product description. These three indexes corre-


spond to a strings in the string descriptor. If there is no string it most be set to zero.The product description for example is the text that pops up in the right corner whenthe device is plugged in to the computer the first time. The Id fields in the devicedescriptor is used to identify the device from which vendor the device comes from andwhat product it is. The last property contains how many configuration descriptors thisdevice has. A device descriptor have at least one Configuration descriptor.[34]

Configuration Descriptor

Each device can have one or more configurations. In this way the host can change theconfiguration depending on the situation which means that only one configuration isactive at the time. The Configuration descriptor itself contains only four fields on topof the two fields that all descriptors have. The first of these four fields contain thelength of this configuration descriptor and all interface and endpoint descriptors thatthis configuration contains. The second and third field contains the number of interfacesthis configuration have and a id of this configuration. The id is used when the host sendsthe setconfiguration request that will set the configuration to the requested id. The lastfield contains an index to the string descriptor that describes this configuration in text.[34]

Interface Descriptor

Each configuration has one or more interface and each configuration have all interfacesactive at the same time. This means that a device can have for example two interfacesagainst the host that represents two different classes of devices. Interfaces can like devicedescriptors be part of a class of devices. An interface descriptor contain both class andsubclass fields. If this setting should have any effect the class and subclass fields in thedevice descriptor have to be set to zero. One may notice when plugging in a mobilephone in a USB port that the operation system installs a number of devices. Which typeof devices can differ, but usually it is a mass storage device and mobile modem device.The interface descriptor contains both class and subclass fields like the configurationdescriptor. If this setting should have any effect the class and subclass fields in thedevice descriptor has to be set to zero. An interface descriptor can also have alternateinterfaces which can be changed from the original interface after the configuration of thedevice. An original Interface descriptor will have to set the alternate interface field tozero, the first alternate interface sets it to one, and so on. All interface descriptor has anid field and all alternate interfaces will set it to its original interface id. In the same wayas the previous types of descriptors, the interface descriptors have a field containing thenumber of descriptor in the level of the tree. In this case it is the endpoint descriptortypes. The last field in the configuration descriptor is the index to a string in the stringdescriptor that should describe what function this the interface had. [34]


Endpoint Descriptor

Each interface has zero or more endpoints. If an interface has no endpoints it uses thedefault control pipe, also called endpoint zero. The purpose of an endpoint descriptor isto define a data pipe between the host and the device. To define the data pipe the end-point uses four fields; attributes, endpoint address, max packet size, and interval field.The endpoint address field can be divided in to two parts, the endpoint number and thedata direction of the endpoint. The endpoint number is a number between one and 15which means that an interface can have 15 endpoints excluding endpoint zero. The datadirection part defines the endpoint to be an IN endpoint or a OUT endpoint. It can’t beboth an in and out endpoint at the same time. This does not apply to a control endpointwhich ignores the data direction bit. The attribute field is divided into 3 parts whichdefines the endpoint’s transfer type and settings. The first part describes which of thefour transfer type the endpoint uses. These four transfer types are Isochronous, control,bulk, and interrupt transfer. This thesis is not going in to details in how these differenttransfer types works. The full description can be found in the USB2.0 specification.[34]

The control transfer type differs from the other three types. The control transfer typehave no direction set in the endpoint address field, because the control transfer type isbi-directional. This means that it sends data in both ways. The control transfer type isprimarily used in endpoint zero which setups the device.[34]

The Isochronously transfer type sets up a pipe which has guarantied bandwidth andconstant rate of data. When a packet is lost or the data in the packet is corrupted theisochronous transfer type drops it and will not try to resend it. This transfer type istherefore used when streaming audio and video where dropped packets are no big issue.Isochronous transfer type is not suited for file transfer or other tasks that depends ofthe data is intact with no errors. The last two parts of the attribute field is only used bythe isochronous transfer type. These two parts of the attribute field describe which typeof synchronization and usage type the isochronous endpoint will use. More informationabout the synchronization and usage type can be found in the USB2.0 specification.[34]

The interrupt transfer type is for small data packages that are sent asynchronous. Thesepackets are guaranteed a maximum specified latency and reliable transfers. Should anerror occur the packet is resent as fast as possible. The interrupt transfer type is usedby HID devices where latency and reliability is key when for example sending bottomclick.[34]

The bulk transfer type is used when reliably sending large data packages without anylatency demand. The bulk transfer type is used in mass storage devices for file transferas described in class specification of bulk mass storage devices[33].

The max package size field and interval field function depends on the transfer typeand device speed is used.[34]


5.1.3 Descriptor objects in SoftUSBDevice

In the DSF framework the four descriptors are represented by four COM objects. Soft-USBDevice represents the device descriptor, SoftUSBConfiguration represents the con-figuration descriptor, SoftUSBInterface represents the interface descriptor, and Soft-USBEndpoint represents the endpoint descriptor. Each of these object holds all theproperties from respective descriptor but some of them have more functions and proper-ties that the simulation uses. When the simulated device gets the request for a descriptorit uses these objects to generate the descriptor and send it back to the host. These re-quests can be caught as an events in DSF. To catch these events a custom event handlerthat implements the ISoftUSBEndpointEvents interface has to be created. The eventhandler then will have to be connected to the SoftUSBEndpoint which will receive theserequests and generate events. These request is usually sent to endpoint zero. The stan-dard getdescriptor(Configuration) request is handled by DSF which sends the descriptortree including the HID descriptor back to the host. The getdescriptor(Report) requestis not handled by DSF. This request needs to be handled by a custom event handler thatcatches the getdescriptor request with the descriptor type value set to report descriptorand returns the report descriptor. This is done with the ISoftUSBEndpointEvents in-terface method OnDeviceRequest which is called when a getdescriptor(Report) requestis sent from the host to that endpoint.[14, 17, 31, 19]

5.1.4 HID Descriptors

The sections above describe how to create a generic simulated USB device. The lastpart of knowledge needed to create a simulated joystick is the HID class of devices. HIDclass devices is devices that takes input from human interaction with the device andtranslates it in to computer understandable form. Examples of HID class devices areranging from a simple mouse or a keyboard to extremely realistic flight joysticks. HIDclass devices are self describing as USB devices are. HID class devices sends descriptorsto the host computer to describe its functions and how to parse data to and from thedevice. This minimizes the need for drivers to manage the device.[31]

HID class devices follows the HID standard which is described in two specifications;HID class definition and HID usage tables[32, 31]. The HID standard can also be usedon other interfaces then USB. In Windows HID is also used on serial, ps\2, and gamingports. The HID class definition however is mainly focusing on the USB bus.[21, 34]

The HID class definition demands that interface and endpoints are defined according tothe HID standard. A HID device must set its interface’s class field to three which is theid for the HID Class. The subclass field is set to zero if it is not a boot device. A bootdevice in the HID sense is a keyboard or a mouse that the BIOS can use. If it is a bootdevice the interface protocol field can be set to one if it is a keyboard or two if it is amouse. If it is not a boot device the interfaces protocol is set to zero. The reason thatthese properties are set in the interface and not on device level is that the device mayhave more interfaces then just the HID interface. As described before a device can havemore than one interface that support different classes of devices. For example an USBdevice can have one interface for Audio and one for HID.[31, 34]

The HID interface requires two endpoints; one interrupt in endpoint and endpoint zerowhich is a control endpoint. The interrupt endpoint is used to send input to the host


with formatted data called reports. Endpoint zero is used to send data to the host whenpolled and receive data from the host. Endpoint zero also responds to request from thehost. The HID interface may also have interrupt out endpoint that is used to send datato the HID device instead of sending it through endpoint zero. Endpoint zero is sharedbetween all interfaces in a configuration. When using multiple interfaces endpoint zeromay be not have the capacity to be used as an out endpoint for feedback from the host.Then the optional out interrupt endpoint is used.[31, 34]

The HID device uses three descriptors to describe itself. These three are the HIDdescriptor, the report descriptor, and the physical descriptor.[31]

The HID descriptor contains general information about the HID device such as countrycode, HID version number, and number of descriptors. The country code is needed todescribe localized hardware for example keyboards which have different setups depend-ing on the language it represents. The number of descriptor field describes how manydescriptors this HID device has. This field has to be set to at least one because thedevice has to contain at least one report descriptor. The physical descriptor is optionaland shall only be used if necessary. The HID descriptor also contains the propertiesof the report descriptor and the optional physical descriptor. When the HID deviceresponds to the USB standard getdescriptor(configuration) request, it inserts the HIDdescriptor between the interface it belongs to and the endpoints of that interface. Thereport descriptor is not sent with the HID descriptor, it is sent in response to the get-descriptor(Report) request. The getdescriptor(Report) request is sent after the deviceis configured.[31, 34]

5.1.5 Report Descriptors

The report descriptor differs from the other descriptors that have been described inthis thesis. The report descriptor does not contain its size or type. That is declaredinstead in the HID descriptor. The report descriptor is not formatted as a table withfields that are in a predetermined place and size. The report descriptor is built up withitems. Almost all items describe a property of the HID device and the other items aresupporting them with various functions. The report descriptor also has another purposethen describing the device. It also describes the format of the report that is sent to orfrom the host with the input or output data from the device.[31]

Figure 5.4 gives an example of an report descriptor that describe a simple joystickwith eight buttons. On the left side is the text description of the joystick which is oneway to explain the report descriptor in human readable form. On the right side is theactual report descriptor in hexadecimal form. The hexadecimal value on one row isequal with the text with the same background color on the same row. The ones withgreen background are items and with the blue background are values or properties ofthe item in front of the value or property. A report descriptor can be very complexto describe complex and specialized devices. But this thesis will only explain the basicreport descriptor in figure 5.4 is the one used later in chapter 6.


Figure 5.4: An image of a report descriptor that describe a HID Joystick.The figureis composed with knowledge from HID class specification,the USB2.0 specification, andHID usage tables specification.

The item that the report descriptor contains can be grouped in to three types; global,local, and main. These three types differ from each other in the way they behave whenparsed. The items that belongs to the main type are the items input, output, feature,collection, and end collection. Three of them; input, output and feature is data itemswhich adds data fields to an input or output report. The collection and end collection isnon-data items and groups the other main items to a collection of controls or feedbackcontrols that is related.[31]

Global and local items differs in scope on which main items is affected. Local itemsonly effect the next main item and global items becomes the default value for that prop-erty. The list of global and local items is long and only the ones that is used in thereport descriptor in figure 5.4 will be described. The table 5.1 show the items from thereport descriptor in figure 5.4 which is then grouped in to the different item types.[31]


Table 5.1: Table over items in figure 5.4.

GlobalUsage PageLogical minimumLogical maximumReport CountReport Size

LocalUsageUsage MinimumUsage Maximum

MainInputCollectionEnd collection

Usage Page

To explain the report descriptor in figure 5.4 each items purpose have to be describedseparately first. First item in the list above is Usage page which decides the page to thenext Usage item belongs to. In this way Usages is grouped in to meaning full groups.For example generic desktop that is used in figure 5.4 contain general usages such asmouse and joystick. Generic desktop also contain more specified usages as X and Yaxis controls which mouses and joysticks are using. Another Usage page is Simulationwhich contain for example usages as flight simulation device and spaceship simulationdevice.[31, 32]

Logical minimum and maximum

Next items are logical minimum and logical maximum which sets the boundery of thevalue that the controls are expected to return. For application this is important to knowwhat the minimum and maximum are, for example when using a joystick the boundariesis used to scale the input in the application.[31]

Report count and Report size

Report count describes how many data field that are added to the report when the nextmain data item is parsed. Report size sets the default size in bits of the field that isadded. [31]

Usage, Usage minimum and maximum

As described in the section about usage pages are usages a representation of one specificcontrol or device that may contain several specific controls. For example mouse is oneusage and a mouse may contain five specific controls X, Y, and two Buttons. The orderof usages is the order they are mapped in the report to the host. To make it easier toadd a group of controls from the same usage page usage minimum and usage maximum


is used. For example the Button usage page contains usages button one to button 65535.To describe eight buttons on a joystick only with usage the report descriptor needs tohave one usage for each button. But with usage minimum and maximum items onlyneeds to one usage minimum set to button one and usage maximum set to button eight.Usage, usage minimum and usage maximum are local items and do only effect the nextmain data item.[31, 32]

Input

The Input item is the last item before the data fields is added to the report. Theinput item describes the attributes of the data fields that are added. The attributesis represented by six switches that each have two opposite states which is shown intable 5.2. Bit 0 decides if the data is constant or contains data. Constant data is oftenused without usage as padding when byte aligning the report descriptor. The reportdescriptor in figure 5.4 is already byte aligned and do not need padding. Bit 1 decidesif the data fields are each an single variable or the field is a Array of data. For examplefour buttons that each has two states; pressed or not can be represented in two ways.When representing the buttons with bit one on the input attributes set to variable eachbutton gets one field with the size of one bit. When a button is pressed its bit changesto one and it can be pressed simultaneously with other buttons in the group. Whenusing bit one set to array instead the buttons are represented by one field that is threebits. Then when one button is pressed its id number is sent in the field, this means thatonly one button can be pressed at the same time. To be able to press two buttons atthe same time the report needs one more field and 3 field to support 3 simultaneouslypressed buttons. Bit 2 decides if the data is absolute or relative. A mouse pointer isalways relative to the position it is in before so the data is the change from the previousposition. A joystick pointer on the other hand always has absolute position. This meansthat the data is the current position. Bit 3 shows if the data should go to its lowestvalue when the maximum value is exceeded and vice versa. Bit 4 decides if the data isscaled linearly or not. Bit 5 decides if the data have a preferred state. Buttons is inpreferred state when it is not pressed. Bit 6 decides if the data is outside of the logicalboundaries and therefor is not considered meaningful can be considered a null value.[31]

Table 5.2: Table over the attribute field of the input item.Bit 0(Default) 10 Data Constant1 Array Variable2 Absolute Relative3 No wrap Wrap4 Linear Nonlinear5 Preferred state No preferred state6 No null state Null state

Collection and End Collection

The collection item has one property that describes what type of collection it is. Thereare seven different types of collections but only two of them will be described here.These two types are application and physical. Application type tells the host that


the data inside the collection is of interest to the applications and may contain onecommon purpose. For example an keyboard can have an integrated pointing device andin the report descriptor the pointing device and the keyboard may be divided into twocollections which both are of application type. In this way the host can divide the devicein two devices which will be easier to handle than handeling every combination of devices.Physical type of collection contains data that is collected in the same geometrical point.For example a pointing device gets the X and Y axis data from the same sensor and istherefore usually in a physical collection.[31]

Joystick Report Descriptor

The report descriptor in figure 5.4 is divided into three groups where one contains theother two. Each of these groups have in the figure 5.4 a box around itself to mark theitems that belongs together.

The outer group that contains the other two groups contains a usage page and a usagewhich specifies that this HID device is a Joystick. The outer group then starts an appli-cation collection to inform DirectInput or other applications where to look for controlsto the joystick. The first inner group begins with a usage page and a usage that specifiesthat this section is about the actual stick on the joystick that is referred to as a pointerin the report descriptor. One note is that the usage page is not necessary in this groupsince the generic desktop page is already defined in the outer group and is thereforealready the default page. It is only added in this report descriptor to make it easier tofollow.

The first inner group then starts a physical collection to group the two axis togetherwhich is measured in the same point. This two axis is specified by the usages X and Ywhich tells the application how to handle the different axis. After the usages the reportdescriptor describes that the axis will have a boundary between -127 to 127. The datais then sett by the report count and report size to be one field each which is 8 bits wide.The data is then specified by an input item which states that this is data, variable and isabsolute. The rest of the input attributes is set to zero which is the default setting. Thisgroup ends the physical collection and in the same time it ends itself. The next innergroup also starts with a usage page but it uses usage minimum and usage maximuminstead of usage. The usage page is set to the buttons page which contains the buttonsfrom one to button 65535 and in that order. Usage minimum and maximum then spec-ifies that button 1 to 8 will be used. The buttons are then specified to be two statebuttons, their values is bound between zero and one. Each of the buttons gets one fieldwith the size of one bit in the report which is specified by the report count and reportsize. The input item specifies that the data has the same attribute as the other innergroups input item which are data, variable, or absolute. The last inner group ends withthe input item and the outer group ends itself with the end of the application collection.This whole report descriptor describes a Joystick whit two axes and eight buttons. Italso states a map over the report data which contains two eight bit fields and eight onebit field. This gives DirectInput all information to use the joystick.[31, 32]


5.1.6 The Report and DSF

When the simulated HID device has sent the report descriptor and the host have receivedit the simulated device is ready to send reports. The reports sent to the host is sentthrough the IN interrupt endpoint. There are two ways it can be implemented in DSF.One is to use the SoftUSBEndpoint method queueINData which adds the report tothe in queue. The in queue is then drained when the host requests data. This is callpolled simulation. The other way is to connect a event handler to the SoftUSBEndpointin the same way as the event handler for endpoint zero was connected. This eventhandler will not handle OnDeviceRequest. Instead it must handle the OnReadTransfer.OnReadTransfer is called when the host requests data and the OnReadTransfer sendsthe report back to the host. This is called an event-driven simulation. The differenceis that the polled version puts the report in a queue and waits for the host to send therequest. The event-driven version generates the report when the simulated HID devicereceives the request for more data. The polled version is easier to test if DirectInputreceives the input but is more difficult to implement in order to handle higher throughputand lower latency. The USB bus architecture makes it a polled bus where the host isalways initiating all data transfers.[19, 18, 34]

This is the last part of information needed to create the simulated joystick. The nextchapter will use this information to implement a simulated joystick prototype.

Chapter 6

Design and Implementation

6.1 Design

Chapter one describes the problems that the solution should solve. This section gives ageneral design of a system that gives a solution to these problems. The level of detailin this design is low because of limited time. The connection to VBS2 was prioritizedbefore a high detailed design because without the connection to VBS2 the design wouldnot have any purpose. The design purpose in this section is to give a picture of howevery part is connected.

The first thing when designing is to locate the problems that the system needs to solve.This system is dependent on two other applications VBS2 and SimBas. This means thatthis system have to handle also there limitations and demands. VBS2 is a FPS(FirstPerson Shooter) which means that the player only plays one character at the time andthe player plays the character as if it was himself in the game. In vehicles in the gamethe characters can have different roles. To control all the vehicle functions, all the roleshave to be controlled. This means that the player needs an instance of VBS2 for everyroll it needs to control. The computational power requirements of VBS2 is quite highwhich means that multiple instances of VBS2 can’t be run on the same computer. Thismeans that a vehicle trainer with a gunner, a driver, and commander then needs threeinstances of VBS2 on three different computers. The different vehicles in VBS2 havedifferent types of roles and can vary in numbers. Therefor the design of the system hasto be dynamic in the case of creating and modifying roles. Chapter three points outthat the best way to control VBS2 is through DirectInput which is done with help fromthe DSF framework

The simulation of the vehicles electrical system and interfacing towards the hardware isdone with SimBas and has to run on a computer of its own.

6.1.1 The hardware

The hardware for the vehicle trainer is set up in the way that VBS2 and SimBas demand,which is discussed above. Each role has a computer of its own connected through a localnetwork to the server that contains SimBas. The structure of the hardware in the systemis illustrated in figure 6.1. There are three computers in the picture; each one has one

27

28 Chapter 6. Design and Implementation

role and one instance of VBS2. Each instance of VBS2 is connected to an VBS2 server.This is not shown in the figure. The lower computer is the server and is running SimBas.All the computers in the system are connected to each other via a local network. Thelocal network of the vehicle trainer can then be connected to any another vehicle trainer,VBS2 server, or a VBS2 client controlled by the instructor.

Figure 6.1: A conceptual image of the system.

6.1.2 The software

The software that handles the connection between the instances of VBS2 and SimBasis called EVCCom(External Vehicle Control Communication) in this design. EVCComhas two parts; the client part and the server part. EVCCom is a distributed systemthat has the responsibility to distribute messages between clients and a server. Thesemessages may be handle differently depending on its priority and if the message can bedropped in case a client is flooded or the messages time to live has expired.

Clients

Each role computer has one instance of the game and one instance of the client partof EVCCom. The Clients communicates with the server part of EVCCom through thecommunications layer. The Clients communication layer takes care of receiving mes-sages and sending messages back to the server. The communication layer filters out themessages that it should not receive or the messages time to live has expired. The clientis the one that knows which messages it should receive not the server. The server sendsall messages to all clients. The communication layer also has the task of delivering mes-sages with higher priority before the one with lower priority. The Order of the messagesis not important because the messages have only one receiver and the clients are notdependent on each other. The client is also enabled to send messages to the server.

6.2. Implementation of Simulated Joystick 29

To connect the Client to the game the system uses Microsoft DirectInput. That isa standard used by most of games running on Windows. DirectInput uses human inputdevices(HID) as input. HID devices is usually a USB device that is plugged in a USBport on the computer. In chapter 3 the Microsoft Device Simulation Framework(DSF)is chose to simulate a USB HID Device in software. The client can then simulate ajoystick and/or a keyboard and the game does not recognize any difference. The HIDdevice can then be changed after which role the client will take and what functions isneeded. The client part of EVCCom may also retrieve information from VBS2 throughthe interface Fusion and may send the information back to the server.

Server

The Server part of EVCCom receives signals from SimBas. The signals are then con-verted to messages with a format the client understands. The communication layer thensends the message to all the clients that are connected. The Server part of EVCComdon’t care which client that should receive the message. This makes it easier to add newroles because almost all the changes is then in the client part.

One important property the system needs to have is that the response time of sys-tem is low. The response time is for example the time it takes from that the driverturns the wheel until the vehicle actually turns in the game. The response time haveto be lower than a human can apprehend. If it is higher, the driver notices it and mayover compensate the movement.

6.2 Implementation of Simulated Joystick

This section of the thesis is going to describe how the simulated joystick is implementedwith the knowledge from the last chapter. The simulated joystick is divided into twoparts; the simulated HID device and the C#/.net - C++/com wrapper. The simu-lated HID device part contain the actual simulated joystick which is implemented inC++/COM. The chapter about DSF explains that DSF is buildup using com-objectwhich means that the simulated HID device also needs to be implemented in a lan-guage that supports COM objects. The DSF framework is also implemented in C++which is another reason why the simulated device is implemented using C++/COM.The Problem chapter explains on the other hand the needs for a C#/.net API againstthe application that controlling the simulated joystick. This is where the C#/.net -C++/COM wrapper comes in. C++/COM and C#/.net are in two different runtimesmeaning for example that they do not share the same memory addressing or handlememory in the same way. The wrapper is there for implemented in C++/cli whichpurpose is to marshal code to the .net runtime from C++. The wrapper contains onlythe methods it needs to keep the API as simple as possible. These methods correspondsapproximately to the states in figure 6.2. The implementation of these two parts isdescribed in the next sections.


The simulated HID device part is implemented to follow the states the DSF requireand DSF derive it from the USB2.0 specification. These states are initiate, configure,plug in, waiting to send/receive, send report, receive report, and unplug. Because thissimulated HID device does not need any feedback the receive state is omitted. Thesestates are connected in the order that DSF required which is shown in figure 6.2. Thesimulated HID device implementation is described below by using these states. The sim-ulated HID device itself implements the ISoftUSBEndpointEvents interface to be ableto enable the simulated HID device to handle events from the host. This is explainedin grater detail in the initiation and configuration section.

Before the simulated device is started the Ehci controller simulator SoftEhci have tobe started as described in the previous chapter. With out SoftEchi the simulated devicecan not plug in the device.

Initiation &Configuration

Waiting to

send

Send report

StartTermination

Plug in the

device

Unplug the

device

Figure 6.2: The state chart for the simulated HID device.


6.2.1 Initiation & Configuration

Initiation and configuration is the first state when the simulated device starts. It ini-tiate all objects that are needed to simulate the joystick and configures them with thecorrect properties which is described in the chapter five. In that chapter it is describedthat a HID device needs a device-, a configuration-, a interface-, a endpoint-, a HID-,and a report-descriptor. These are all represented as objects in DSF except the reportdescriptor and hid descriptor. The Objects that are initiated are listed in table 6.1.

Table 6.1: Table over the objects that is initiated.

DSFSoftUSBDevice

SoftUSBConfigurationSoftUSBInterfaceSoftUSBEndpoint

6.2.2 Configuration

When the object has been initiated the simulated HID device configures these objects.The first object that is configured is SoftUSBDevice which is followed by the nextobject in the list above. When all descriptor objects are configured they are assembledto the tree structure described in chapter five with figure 5.3. The tree is built up fromthe bottom up and beginning with SoftUSBEndpoint. The SoftUSBEndpoint objectis is added to the SoftUSBInterface endpoint list and the SoftUSBInterface is addedto the SoftUSBConfiguration interface list. The SoftUSBConfiguration is added to theSoftUSBDevice configuration list.

SoftUSBDevice

SoftUSBDevice is configured to simulate an USB2.0 device and do not specify the deviceto belong to a specific class or protocol. This is set in the interface object as chapter fivestates. The manufacturer, product description, and serial number string index numberis also specified. The number corresponds to the index of the right string in the stringdescriptor. The string descriptor in DSF is a property to SoftUSBDevice in the formof the object SoftUSBStrings. SoftUSBStrings contains a list of SoftUSBString. Whenthe simulated HID device is configured the strings is added to the SoftUSBStrings as aSoftUSBString. The device-, vendor-, and product-number is set to a random constantnumber that do not corresponds to a real device-, vendor-, or product-number specifiedby USB implementers forum. The device is also configured to be bus powered andrespond to remote wake up calls. This is done only to the simulated device, becausethe device descriptor does not contain these properties. The SoftUSBDevice use thesesettings to handle the getstatus request sent by the host. The configuration descriptoron the other hand contains this properties in it’s own attribute field which is used bythe host to know what to expect from the getstatus request. This is an example of thetwo sides of DSF objects mentioned in chapter five.


SoftUSBConfiguration

SoftUSBConfiguration have four properties that need to be configured. The first one isthe id of the descriptor which in this case is one. The second one is the attribute fieldthat is part of the configuration descriptors is configured to be a bus powered deviceand it will respond to remote wakeup calls. The third is the SoftUSBString index forthe string that describe this configuration. The last property is the maxpower attributethat informs the host what amount of current it will needs from the bus. Clearly this isirrelevant for a simulated HID device but is used testing firmware that handles switchingbetween different power sources. The maxpower is set to 100mA which is the defaultvalue.

SoftUSBInterface

The SoftUSBInterface is configured to belong to the HID class of devices. The subclassis set to zero because this is not a boot device. The protocol is also set to zero to becausethis shall be a joystick which is not a mouse or keyboard. HID class of devices needsthe HID descriptor to describe it’s properties. The HID descriptor is there for added asan device class specific descriptor to the SoftUSBInterface.

This simulated USB device has only one interface which means that this SoftUSBInter-face has id zero and alternate interface id is also zero. The SoftUSBInterface has as allof the other descriptor a string descriptor index that is set to the string that describesthis interface in human readable text.

SoftUSBEndpoint

The SoftUSBEndpoint is the last to be configured. This simulated HID device hasonly two endpoints; endpoint zero and a in interrupt endpoint which is explained inchapter five. Endpoint zero is the default endpoint and do not need configuration.Endpoint zero is only attached to the simulated HID device which implements theISoftUSBEndpointEvents interface which handles incoming events. This is done to beable to for example respond to HID class specific requests. More on this topic will behandled later on in this thesis. The in interrupt endpoint is configured to have theendpoint address 81 which mean that this endpoint has the address one and the eightmeans that this is an in endpoint. This endpoint have attribute field configured to be ainterrupt endpoint. The endpoint has also the maxpage size set to 8 bytes, the intervalto 10 and halted to false.

HID descriptor & Report Descriptor

The HID descriptor and Report Descriptor are not represented in the DSF framework.They are instead built up in two different arrays of bytes. The report descriptor isbuilt up as the report descriptor in figure 5.4. To get a better understanding of thereport descriptor read the report descriptor section in chapter 5. The HID descriptor isconfigured to follow the HID class specification version 1.11 and the country code is setto zero because the device is not localized. The HID descriptors number of descriptorfield is set to one because the simulated HID device has only one HID class descriptorwhich is the report descriptor. The type and length of the report descriptor is added inthe end of the HID descriptor.


Eventhandling

A custom event handler is necessary in a simulated HID device to be able to send thereport descriptor to the host. The simulated HID device implements ISoftUSBEnd-pointEvents interface which have been described earlier in this thesis. This is the firststep in creating a custom event handler. The second step is to connect the event han-dler to endpoint zero which will be the endpoint that receives the getdescriptor(report)request. The event handler’s task is to catch that request and respond with the reportdescriptor. If the simulated HID device had been a event driven device instead of apolled device. Then the event handler had to handle the getreport(report) request too,which returns the report containing the input data to the host.

6.2.3 Plug in and Unplug the device

When all objects are configured the device is ready to be plugged in to the SoftEhci con-troller. The initiation and configuration state initiates the DSF object which is crucialto find the SoftEhci controller. The DSF object contains all objects that are connectedto the framework shown in figure 5.2. One of those objects is the SoftEhci controller.To locate the SoftEhci controller the interface identifier is used. The interface identi-fier is part of the C++/COM which enables us to check if an object follows a specificinterface. The list of connected DSFDevice objects is then searched through and theSoftEhci object is retrieved. The SoftEhci Object that is retrieved contains a SoftEhci-RootHubPorts which is a list of SoftEhciRootHubPort. The simulated HID device canbe plugged in to every one of the SoftEhciRootHubPort. The first available is chosen.The SoftEhciRootHubPort has the HotPlug method which is used to plug in a SoftUSB-Device to the simulated Ehci controller. The HotPlug method uses a DSFDevice objectas input. The simulated HID device retrieves the DSFDevice object from SoftUSBDe-vice that it has initiated and configured. The HotPlug method is then used with thatDSFDevice and the simulated device is attached to the simulated Ehci controller. Thesimulated HID device will then appear in Windows as an real HID device and sends thegetdescriptor(report) request to the device which responds with the report descriptor.The device will then appear to Windows as a real Joystick with eight buttons.

When the simulated HID device is finished and the device is ready to be unpluggedit uses the same SoftEhciRootHubPort object. The SoftEhciRootHubPort also have themethod Unplug which unplugs the DSFDevice that is attached to that port. When theUnplug method is executed the simulated HID device is removed from Windows in thesame way as when a real USB device is unplugged physically from the computer. TheDSF object is still configured and can be plugged in at any time again.

6.2.4 Sending reports

When the device is plugged in, the device is ready to send reports. The simulatedHID device method sendInputReport is used to send the reports. That method can becalled by the application that wants to steer the simulated HID device. The methodhas two attributes the report as a byte array and an integer which is the size of thatarray. The format of the report is described by the report descriptor which is shown infigure 5.4. The report starts with two eight bit fields which contain first the X axis andthen Y axis. These two axis have a bound between -127 to 127 which the fields shouldfollow. After the two eight bit fields will follow eight one-bit fields which each represents


a button. It begins with button one and ends with button eight. The simulated HIDdevice sends the reports from the IN interrupt endpoint by calling the SoftUSBEndpointmethod queueINData. QueueINData adds the report to a queue which is then drainedwhen the host requests data. This way to implement the report communication is notoptimal. This solution will work as long as few reports is sent at a low frequency. Ifthe reports are sent faster the queue may be flooded. This can be overcome by usingevent-driven simulation. But because the simulated HID device is a prototype and dueto lack of time, the simulated HID device uses polled simulation. The polled simulationgives a good picture of the simulated HID device capabilities of steering a game throughDirectInput.

6.2.5 Termination

When the simulated device is unplugged it can safely be terminated. When terminatedit removes the event handler and uninitiate all objects and removes them from thememory.

6.2.6 C#/.net - C++/com wrapper

The C#/.net - C++/com wrapper is implemented to enable the rest of the training sys-tem to be implemented in C#/.net. The wrapper takes the public methods of the simu-lated HID device and marshal the code between C#/.net(.net) and C++/COM(Native).The wrapper is implemented in C++/CLI which is language that can operate both in.net and native runtime. The wrapper has five methods and two of those methods haveattributes that have to be marshaled. The first one is the InitiateSimulatedDevice whichtakes .net System::Stringˆthat contain the product description of the device. The .netSystem::Stringˆtype can not be sent to the simulatedHIDDevice. The string has to bemarshaled to the native type BSTR. This is done with the class marshal context whichcopies the string and convert it to a BSTR. The BSTR is then used when calling thesimulated HID device InitiateSimulatedDevice. Marshal context object will hold the al-located memory of the BSTR until the marshal context destructor is called which is donein the wrapper uninitiateSimulatedDevice mothod. The second one is the method Send-InputReport. SendInputReport takes two attributes; a cli::array¡byte¿ and a ULONG.The array is the report that the device sends to the host and the ULONG is the size ofthat device. The array is then copied to a allocated memory space. The Byte pointeris then passed on to the simulated HID device SendInputReport. The ULONG valuedo not net to be marshaled and is therefor sent forward untouched. When creating amarshaling wrapper it is important to keep in mind, that the object passed between theruntimes is kept as simple as possible. If they are too complex and have hidden objectit is easy to miss a object that needs to be marshaled. The best way is to only usestandard types which in most cases can be marshaled.

Chapter 7

Results and Conclusions

7.1 Discussion

This thesis is coming to an end, but there is one thing that needs to be discussed. It isthe question if the goals stated in the beginning are met or not. BAE Systems Hagglundsstated one goal that was divided into three subgoals that they wanted to be fulfilled.The overall goal was to investigate if it is possible to make a vehicle training systemwith VBS2 as the virtual environment. The first subgoal was to find a way to interactwith VBS2. The second subgoal was to design a prototype system and the third was toimplement the most important part of that system.

The first subgoal has been satisfied and is described in chapter three, four, and five.Those chapters find two ways to interact with VBS2 and one way was chosen to bestudied closer and implemented. The second sub goal is satisfied and described in sec-tion 6.1. That section presents a general design of a vehicle training system that usesthe knowledge presented in chapter two,three, four, and five. Appendix A contains therequirements list that was generated from the design and pre-study. All the ”shall”requirements in the list mirror the third goal.

The last subgoal is satisfied and described in section 6.2. In tests the prototype showedthat it could create and control a joystick. These tests are in its nature visual andcan’t be described in numbers or text here. Figure 7.1 shows the game controller setupscreen in Windows with the simulated device plugged in. Left side in the picture is thedevice manger and the two marked HID devices are the simulated HID device. In themiddle there is the gamecontroller panel which shows the the simulated joystick andthe status of the device. The name displayed in the gamecontrollers panel comes fromthe product description string set in the device descriptor which is described in section5.1.2. Below the gamecontrollers panel in the middle is the gamecontroller configurationwindow which can be used to see the input from the simulated joystick to the computer.To the right is a GUI of the simulated joystick prototype. The top text-bar in the GUIcontains the product description that is used by the simulated joystick. The X and Ytext-bar contain the coordinates which is used when pressing the Move device button.In the figure 7.1 the move button has been pressed and the gamecontroller configura-tion window shows the same coordinates that were sent from the GUI to the simulatedjoystick.

35

36 Chapter 7. Results and Conclusions

Figure 7.1: A screenshot in Windows showing the prototype just after it have movedthe simulated joystick.

7.2. Future work 37

7.2 Future work

This thesis is only the starting point of a larger project. This means that the thesisshould be seen as a technical study to pave the way for a larger project. There areseveral parts to complete the system and some of them are described below.

The implemented part of the system is a prototype and its main purpose is to actas a ”proof of concept” in how to control VBS2 with an external application. The pro-totype has to be evaluated in greater detail. One detail that need closer evaluation isthe method in sending of reports through the endpoint to the host. The method mayhave to be changed to an event-driven simulation to lower the response time.

The new features and capabilities in the new version 2.0 of the VBS2 plug-in Fusionhas to be evaluated. This was not investigated in detail in my project because BohemiaInteractive had not released Fusion and any details about Fusion v2.0 during the writingof this thesis.

The current design of the system is a coarse grained design and have to be designedin greater detail. One detail that has to be added is how the connection layer prioritizemessages and send them in a reliable way.

38 Chapter 7. Results and Conclusions

Chapter 8

Acknowledgements

I would like first of all to thank BAE System Hagglunds for offering me the opportunityto work on this project. I would like to thank my supervisor Johan Persson at BAESystem Hagglunds which gave me all the support, equipment and software I needed tofinish the practical part of the thesis. I would also thank Erik Essegard at BAE SystemHagglunds for all the technical advice he gave me during the practical part of the thesis.

At Umea University I would like to thank my internal supervisor Jonny Petterssonthat guided me through the whole work process of this thesis. I also want to thank PerLindstrom for taking the time to read the thesis and give feedback.

I would like to thank Eric Olofsson for checking the thesis for grammatical errors. Ialso like to thank every one that supported me in some way during the time I workedon this master-thesis.

Last I like to give special thanks to my Mother and Father for all the support theyhave given me during this master-thesis. Without them this thesis might not have beenfinished.

39

40 Chapter 8. Acknowledgements

References

[1] Bae systems hagglunds homepage. http://www.baesystems.com/AboutUs/index.htm(Accessed 2009-11-20).

[2] Bohemia Interactive Australia. White paper: Vbs2. http://distribution.vbs2.com/docs/VBS2_Whitepaper.pdf(Accessed 2010-01-05).

[3] National Semiconductor Compaq, Microsoft. OpenHCI - Open Host Controller In-terface Specification for USB. ftp://ftp.compaq.com/pub/supportinformation/papers/hcir1_0a.pdf(Accessed 2010-04-25).

[4] Intel. Universal Host Controller Interface (UHCI) Design Guide. http://

download.intel.com/technology/usb/UHCI11D.pdf(Accessed 2010-04-25).

[5] Intel,Compaq, Nec, Lucent, Microsoft. Enhanced Host Controller Interface Spec-ification for Universal Serial Bus. http://www.intel.com/technology/usb/

download/ehci-r10.pdf(Accessed 2010-04-25).

[6] Bohemia Interactiv. Bohemia interactiv company profile. http:

//www.bisimulations.com/sites/default/files/images/Handouts/BISIM_

Company_profile_preview.pdf(Accessed 2010-10-14).

[7] Bohemia Interactive. About vbs2. http://virtualbattlespace.vbs2.com/

index.php?option=com_content&task=view&id=81&Itemid=97(Accessed 2010-03-15).

[8] Microsoft. Bus drivers. http://msdn.microsoft.com/en-us/library/

ff540704(VS.85).aspx(Accessed 2010-03-18).

[9] Microsoft. Device objects and device stacks. http://msdn.microsoft.com/en-us/library/ff543153(VS.85).aspx(Accessed 2010-03-18).

[10] Microsoft. Device simulation framework design guide. http://msdn.microsoft.

com/en-us/library/ff538293(VS.85).aspx(Accessed 2010-03-18).

[11] Microsoft. Directinput. http://msdn.microsoft.com/en-us/library/

ee416842(VS.85).aspx(Accessed 2010-03-09 ).

[12] Microsoft. Directinput (windows driver kit). http://msdn.microsoft.com/en-us/library/ff538540(VS.85).aspx(Accessed 2010-03-18).

[13] Microsoft. Drivers for the supported usb device classes. http://msdn.microsoft.com/en-us/library/ff538820(VS.85).aspx(Accessed 2010-03-18).

41

42 REFERENCES

[14] Microsoft. Dsf architecture. http://msdn.microsoft.com/en-us/library/


[15] Microsoft. Dsf object model. http://msdn.microsoft.com/en-us/library/


[16] Microsoft. Dsf usb 2.0 bus simulator (softehci). http://msdn.microsoft.com/

en-us/library/ff538329(VS.85).aspx(Accessed 2010-03-18).

[17] Microsoft. Dsf usb device simulator (softusbdevice). http://msdn.microsoft.


[18] Microsoft. Dsf usb loopback device simulation. http://msdn.microsoft.com/


[19] Microsoft. Event-driven and polled simulation. http://msdn.microsoft.com/


[20] Microsoft. Hclient. http://msdn.microsoft.com/en-us/library/ff538800(VS.85).aspx(Accessed 2010-03-18).

[21] Microsoft. Hidclass devices. http://msdn.microsoft.com/en-us/library/


[22] Microsoft. Idsfbus interface. http://msdn.microsoft.com/en-us/library/


[23] Microsoft. Installing dsf. http://msdn.microsoft.com/en-us/library/


[24] Microsoft. Kernel-mode. http://msdn.microsoft.com/en-us/library/


[25] Microsoft. Layered driver architecture. http://msdn.microsoft.com/en-us/

library/ff554721(VS.85).aspx(Accessed 2010-03-18).

[26] Microsoft. Operation of the hid class driver and hid minidrivers. http://msdn.

microsoft.com/en-us/library/ff543200(VS.85).aspx(Accessed 2010-03-18).

[27] Microsoft. Overview of system components for driver writers. http://msdn.

microsoft.com/en-us/library/ms791641.aspx(Accessed 2010-03-09 ).

[28] Microsoft. Usb driver stack for windows xp and later. http://msdn.microsoft.


[29] Michael Barlow; Peter Morrison. Challenging the super soldier syndrome in 1st per-son simulations. In SimTecT Papers 2005. SIAA(Simulation Industry Associationof Australia), 2005. http://www.siaa.asn.au/get/2411856229.pdf.

[30] Bohemia Interactive Simcentric. Vbs2fusion - a c++ api for vbs2,feature list. http://www.simcentric.com.au/downloads/SL-SIM-FUSION_

VBS2FusionFeatureList_v1.2.pdf(Accessed 2010-03-15).

[31] USB Implementers Forum, Inc. Device Class Definition for Human Inter-face Devices (HID). http://www.usb.org/developers/devclass_docs/HID1_11.pdf(Accessed 2009-12-16).

REFERENCES 43

[32] USB Implementers Forum, Inc. HID Usage Tables. http://www.usb.org/

developers/devclass_docs/Hut1_12.pdf(Accessed 2009-12-16).

[33] USB Implementers Forum, Inc. Universal Serial Bus Mass Storage Class- Bulk-Only Transport. http://www.usb.org/developers/devclass_docs/

usbmassbulk_10.pdf(Accessed 2010-04-20).

[34] USB Implementers Forum, Inc. Universal Serial Bus Specification. http://www.

usb.org/developers/docs/usb_20_081810.zip(Accessed 2010-04-01).

[35] Michael Zyda. From visual simulation to virtual reality to games. Computer, 38:25–32, 2005.

44 REFERENCES

Appendix A

Requirements

The key words ”MUST”, ”MUST NOT”, ”REQUIRED”, ”SHALL”, ”SHALL NOT”,”SHOULD”, ”SHOULD NOT”, ”RECOMMENDED”, ”MAY”, and ”OPTIONAL” inthis document are to be interpreted as described in RFC 2119.

A.1 User Requirements

1. This system SHALL be a prototype to investigate if the game VBS2 could beintegrated to SimBas and be a virtual environment for a Vehicle trainer.

2. The system SHOULD be easy to expand and modify, to be able to handle thedifferent roles that a vehicle trainer can contain.

3. Each role SHOULD be able to have an own set of functions.

4. Each role SHOULD have an own instance of the game and the client part of thesystem.

5. The different parts of the system SHOULD be reusable and modular.

6. The simulation and connection to the hardware of the vehicle SHALL be handledby SimBas.

7. The distributed system part SHALL be loosely coupled and dynamic designed.

8. Client Server implementation SHALL work over a local network whit in the vehicletrainer.

9. Client Server implementation SHALL work on Windows XP.

10. Client Server implementation MAY work on Windows Vista, 7.

11. The Client SHALL be able to interact with the game through Directinput.

45

46 Chapter A. Requirements

A.2 System Requirements

Functional Requirements

1. The Client SHALL be implemented.

1.1 A Simulated USB device SHALL be implemented.

1.1.1 The simulated USB device SHALL be a HID device.

1.1.2 The simulated USB device SHALL use Windows device simulation frame-work.

1.1.3 The simulated USB device SHALL use Directinput to connect to thegame.

1.1.4 The simulated USB device SHALL have an interface for other applica-tions to use.

1.1.5 The simulated USB device SHALL have a function to decide which hiddevice it will simulate.

1.1.6 The simulated USB device SHALL be able to steer the game from anotherapplication.

1.2 The Client SHOULD be able to take different roles.

1.2.1 The Client SHOULD only take one role at the time.

1.2.2 The Client SHOULD know which role it is.

1.2.3 A role SHALL be implemented as module.

1.2.4 The role module SHALL be able to describe to the client which messagesit SHALL receive.

1.2.5 The role module SHALL know what to do with the messages.

1.2.6 The role module SHALL be able to interact with the game through thesimulated USB device.

1.2.7 The role module SHOULD be able to interact with the game through acustom interface.

1.2.8 The role module MAY be able to modify the input before it sends it tothe game.

1.3 The role for the driver SHOULD be implemented.

1.3.1 OPTIONAL Functions.

1.3.1.1 Start the Engine

1.3.1.2 Stop the Engine

1.3.1.3 Gear

1.3.1.4 Ramp Control

1.3.2 REQUIRED Functions.

1.3.2.1 Steering

1.3.2.2 Brake

1.3.2.3 Throttle

1.3.2.4 Blinkers

1.3.2.5 Position/Headlights lights

1.3.2.6 Night vision on/off

1.3.2.7 Open/Close hatch

A.2. System Requirements 47

1.3.3 The driver role MAY be able to send statistics to server.

1.3.3.1 Fuel

1.3.3.2 Velocity

1.4 The role for the gunner MAY be implemented.


1.4.1.1 Deploy smoke screen


1.4.2.1 Control the gun

1.4.2.2 Fire the gun

1.4.2.3 Chose weapon

1.4.2.4 Measure distance

1.4.2.5 Position/Headlights lights



1.5 The role for the commander MAY be implemented.


1.5.1.1 Give orders


1.5.2.1 Control the reconturret



2. The Server MAY be implemented.

2.1 The server SHOULD have an interface against the hardware part.

2.2 The server SHOULD be able to handle massages from the users and sendthem to the hardware part.

2.3 The server MAY convert messages from SimBas and send them to the clients.

3. Client/Server

3.1 Both the Client and the Server SHOULD have a communication layer.

3.1.1 The communication layer SHALL be able to send and receive messages.

3.1.2 The communication layer SHALL use multicast.

3.1.3 The communication layer SHALL be able to do unreliable multicast.

3.1.4 The communication layer MAY use a priority queue to send and receive.

3.1.5 The communication layer MAY use reliable multicast.

3.2 The time from the server gets a message from the SimBas side to the clienthas passed the message on to the game SHALL be lower than the humanapprehension time.

3.3 The Client and the server SHALL have a GUI for configuration and testing.

3.3.1 The GUI MAY save the configuration to disk.

3.3.2 The Client SHALL be able to start without the GUI.

3.3.3 The Client MAY use a Saved configuration when started.

48 Chapter A. Requirements

4. The system MAY be connected to SimBas.

Non-functional Requirements

1. Product requirements

1.1 The system SHOULD be a prototype of future system.

1.2 The system SHOULD be a proof of concept.

1.3 The system SHOULD use VBS2.

1.4 The system MAY used to interact whit other games.

2. Organizational requirements

2.1 The system SHALL be implemented in C++/cli and/or C♯ .net.

mikael svensson - um) - u

Documents