Post by Frisbone on Jul 12, 2013 11:59:50 GMT -5
Inertial Targeting Controller (ITC) Software
Design Document
There are 15 GPIO on the RPi. That gives me 7 pairs of pins that can be used for mapping and one extra pin.
Mapping is important from a flexibility point of view. Lets say that there is another game where the
reload feature is not mapped to the X button, but Y instead - would be nice to change the software instead
of the hardware.
Lets say that someone doesn't like the fact that the leathals are mapped to the left-hand index finger
button - perhaps they would like it on the thumb button instead. So, we can have 7 input buttons (from the
gun itself), and 7 output buttons (controller buttons) - we just need to figure out which ones exist and
then allow the software to map them. Assuming two are used for I2C interrupts we can only use 6 - but we
could adopt a polling design.
First we define all of the components in the system:
components
Accelerometer
Joystick PWM - X/Y free look
Joystick PWM - Trigger - mapped to gun trigger
Controller PWM - Aim
Joystick Buttons - X, Y, A, B, LB, RB, <, >, DPAD Up/Down/Left/Right,
- X = Mapped to reload action on gun
- A = Generated when a "jump" profile is detected by accelerometer
- LB = Mapped to new button on left-hand thumb position (tacticals)
- RB = Mapped to left-hand index finger position (lethals)
- <> = mapped on top of gun, no finger in natural position for them
- DPAD = Entire dpad is mounted on the back of the gun - will have to shift hand poition a bit to
press on it. It is mounted external - so it won't go through our system
- Y = Not sure what it does in game, but map to a left hand pinky button
- B = Not sure what it does, but map to left hand ring finger
- Right stick Down - Not sure what it does but make it a pressure "squeeze" switch on the gun stock
maybe?
Temporarily mapped buttons (in a fully integrated system, won't need them on a joystick)
- The plan was for the left stick to be mounted on the gun - but connected to the controller so no
electronics intervention is required. Eventually a separate motion system will be used.
Free GPIO:
GPIO PIN
---- ----
4 7
7 26
8 24
9 21
10 19
11 23
14 8
15 10
17 11
18 12
22 15
23 16
24 18
25 22
27 13
New Gun buttons:
NAME PIN Position on gun
---- --- ------------------------------------------------
TRIG NC Gun trigger - software transled to PWM
RLOD 7 Pull spring action trigger on back of gun
THMB 8 Left side of gun on hand brace (right handed person) in position of thumb
LIDX 10 Right side of gun on hand brace (RH person) in the index finger position for left hand
TOPA 24 Top of gun, forward button
TOPB NC Top of gun, rear button
PINK 11 Right side of gun on hand brace (left hand of RH person) in the pinky finger position
RING 12 Right side of gun on hand brace (left hand of RH person) in the ring finger position
GRIP 13 A button that triggers when squeezing the grip
SYNC NC Sync button on top of gun far rear position, hard to press
Note: TOPB is connected directly through HW to the STRT button on the controller, not controlled by RPi.
Not ideal, but limited GPIO for RPi - whem moving to real microcontroller we'll have more options.
Controller buttons:
NAME PIN Purpose in COD
---- --- -----------------------------------------------
X 15 Reload the weapon
Y 16
A 18 Jump - internally generated action
B 19
LB 21 Tacticals - throwing
RB 22 Lethals - throwing
LSTK 23 Right Stick down
< 26 Options menu, in-game status usually
STRT NC Start button
SYNC NC
Internally generated events:
NAME Description
---- ------------------------------------------
JUMP Detected Acceleration profile indicating person jumped
AIM Detected temporary raising of gun, toggles AIM state, reversal also detected
MOVX Simulate movement in the X direction
MOVY Simulate movement in the Y direction
I2c Related I/O (if ultimately we decide to connect):
NAME PIN Purpose in Accelerometer
---- --- -----------------------------------------------
INTA 24 Need to look up
INTB 26 Need to look up
PWM Device Reference:
NAME Description
---- -------------------------------------------------
RJYX X axis of the right joystick
RJYY Y axis of the right joystick
LTRG Left trigger
RTRG Right trigger
Mapping overview:
The following inputs and internally generated events constitute all the items that need to be mapped: RLOD,
THMB, LIDX, TOPA, PINK, RING, GRIP, JUMP, AIM, MOVX, and MOVY. There are 11 in total. 2 of these are
restricted to PWM outputs because they produce varying values (MOVX, MOVY).
The following outputs exist X, Y, A, B, LB, RB, LSTK, <, RJYX, RJYY, LTRG, and RTRG. There are a total of
12, 4 of which are PWM outputs (which we'll call analog for purposes of differentiating them from switch
signals). The MOVX and MOVY are likewise called analog inputs so can only be mapped to analog outputs.
Digital inputs can however be mapped to analog outputs - this is done by outputting the maximum value.
Software shall validate the mapping is complete. There is one more output than input because the right
stick down feature currently is not used - as I'm aware anyway, but this is a future enhancement to
consider. Validation ensures all 11 inputs are mapped, Analog maps only to analog, no repeated mapping
assignments (all unique).
Accelerometer Discussion:
I think that when the gun is in use there may actually be more events generated via interrupt than if you
simply implemented a polling scheme leading to non-deterministic behavior. Probably best to remove the
interrupt tracking and free up pins 24/26.
Architecture:
Device Drivers -
PWM Driver - Generic ability to turn on/off a "value" on a specific device for a specific amount of
time. Will control 4 PWM devices (X-Right Stick, Y-Right Stick, Right Trigger, Left Trigger)
AM Driver - Talks to the accelerometer and regularly polls it for delta changes in G's pulled in all
AXIS directions (X - left/right, Y - Up/Down, Z- Forward/Backwards). If an identified threshold is exceeded
then it outputs an event indicating how much it moved (percent of max G) over what period of time in each of
the axis. The driver also looks for JUMP and AIM profiles. Aim profile will generate a toggling event
indicating the current state (allowing receiver to toggle it as well). Jump is simply an single event with
no state tracking. A Jump is profiled by looking for significant G's pulled in the -Y direction. AIM is
detected with a smaller -Y but more consistent pulled over a longer period of time (say 1/2 second as
opposed to a big pulse for a jump).
Digital I/O - This driver accepts the mapping file as input as well as a software interface for
events. The following Pins will be configured as inputs: 7 (GPIO_04), 8 (GPIO_14), 10 (GPIO_15), 24
(GPIO_08), 11 (GPIO_17), 12 (GPIO_18), 13 (GPIO_27). The following pins will be configured as outputs:
15 (GPIO_22), 16 (GPIO_23), 18 (GPIO_24), 19 (GPIO_10), 21 (GPIO_09), 22 (GPIO_25), 23 (GPIO_11), 26
(GPIO_07). The driver is interrupt driven on all of the input pins. When an input is triggered (rising
edge, trailing edge) - it immediately triggers is "partnered" ouput. If that output is an analog mapped
device (PWM) then it generates an event for it. The driver also accepts software inputs to turn on/off
outputs that are mapped that way. Inputs that trigger with a non-digital output mapped (or no output
mapped) are forwarded as events to the main input event handler. The driver will also allow the application
to define "Combo events" which get sent when multiple input lines are "ON" simultaneously.
Glue Logic -
3D to 2D mapping - The accelerometer outputs events that indicate movement in 3D space based on
percentage of max G's pulled in each direction. This information must be converted to movement of the
Joystick which is a 2 axis device. The conversion is done and the PWM driver is told what to do based on
the data (mapping file consulted on which PWM device as well).
Input Event handler - Discrete events can be triggered without a digital output mapped (like the
main trigger button). Software events can also be received detecting a JUMP, or AIM condition. The IEH's
job is to turn these events into actions - typically by mapping them to the appropriate PWM device.
Administration -
Calibration - it is anticipated that we might need to calibrate movement, and jump/aim detection. A
process for doing this needs to be triggered via a button. It will be triggerd via a defined "Combo" event
requiring that the following inputs be ON: TRIG, TOPA
Properties - Will be in the code because arduino won't have a file system.
Detailed Design:
The ultimate production goal with this device would be to migrate to a more efficient microcontroller that
doesn't have all the RPi overhead (linux, HDMI, ethernet, devices, etc). All we need is a good I/O device
that can do some fairly simple math. But in the end an RPi is very convenient as a test platform. It is
important that we don't finish the prototype software just to find out that we have to re-invent it because
you couldn't put it on an arduino. Thus we should go into this assuming that we will be limited to what is
available on Arduino (no linux, no use of sockets, no file system, no QT or other libraries that aren't
available in the Arduino world, no IPC, no multi-threading). Basically anything complex I'll need to invent
and every IO function needs to mimic the arduino API so I don't have to rework things later on:
arduino.cc/en/Reference/HomePage
Much that we have to do manually in the RPi world just works in the Arduino world (DIO, PWM, etc). Luckily
it seems that the Gordon fellow I got the wiringPi library from actually emulated the arduino functions:
projects.drogon.net/raspberry-pi/wiringpi/
DO NOT USING MULTI-THREADING. Its not possible in the arduino world.
namespace - ITC
PWMDriver class
AMDriver class
DIODriver class
3D2DMapping class
EventHandler class
Calibration class
Properties class
Design Document
There are 15 GPIO on the RPi. That gives me 7 pairs of pins that can be used for mapping and one extra pin.
Mapping is important from a flexibility point of view. Lets say that there is another game where the
reload feature is not mapped to the X button, but Y instead - would be nice to change the software instead
of the hardware.
Lets say that someone doesn't like the fact that the leathals are mapped to the left-hand index finger
button - perhaps they would like it on the thumb button instead. So, we can have 7 input buttons (from the
gun itself), and 7 output buttons (controller buttons) - we just need to figure out which ones exist and
then allow the software to map them. Assuming two are used for I2C interrupts we can only use 6 - but we
could adopt a polling design.
First we define all of the components in the system:
components
Accelerometer
Joystick PWM - X/Y free look
Joystick PWM - Trigger - mapped to gun trigger
Controller PWM - Aim
Joystick Buttons - X, Y, A, B, LB, RB, <, >, DPAD Up/Down/Left/Right,
- X = Mapped to reload action on gun
- A = Generated when a "jump" profile is detected by accelerometer
- LB = Mapped to new button on left-hand thumb position (tacticals)
- RB = Mapped to left-hand index finger position (lethals)
- <> = mapped on top of gun, no finger in natural position for them
- DPAD = Entire dpad is mounted on the back of the gun - will have to shift hand poition a bit to
press on it. It is mounted external - so it won't go through our system
- Y = Not sure what it does in game, but map to a left hand pinky button
- B = Not sure what it does, but map to left hand ring finger
- Right stick Down - Not sure what it does but make it a pressure "squeeze" switch on the gun stock
maybe?
Temporarily mapped buttons (in a fully integrated system, won't need them on a joystick)
- The plan was for the left stick to be mounted on the gun - but connected to the controller so no
electronics intervention is required. Eventually a separate motion system will be used.
Free GPIO:
GPIO PIN
---- ----
4 7
7 26
8 24
9 21
10 19
11 23
14 8
15 10
17 11
18 12
22 15
23 16
24 18
25 22
27 13
New Gun buttons:
NAME PIN Position on gun
---- --- ------------------------------------------------
TRIG NC Gun trigger - software transled to PWM
RLOD 7 Pull spring action trigger on back of gun
THMB 8 Left side of gun on hand brace (right handed person) in position of thumb
LIDX 10 Right side of gun on hand brace (RH person) in the index finger position for left hand
TOPA 24 Top of gun, forward button
TOPB NC Top of gun, rear button
PINK 11 Right side of gun on hand brace (left hand of RH person) in the pinky finger position
RING 12 Right side of gun on hand brace (left hand of RH person) in the ring finger position
GRIP 13 A button that triggers when squeezing the grip
SYNC NC Sync button on top of gun far rear position, hard to press
Note: TOPB is connected directly through HW to the STRT button on the controller, not controlled by RPi.
Not ideal, but limited GPIO for RPi - whem moving to real microcontroller we'll have more options.
Controller buttons:
NAME PIN Purpose in COD
---- --- -----------------------------------------------
X 15 Reload the weapon
Y 16
A 18 Jump - internally generated action
B 19
LB 21 Tacticals - throwing
RB 22 Lethals - throwing
LSTK 23 Right Stick down
< 26 Options menu, in-game status usually
STRT NC Start button
SYNC NC
Internally generated events:
NAME Description
---- ------------------------------------------
JUMP Detected Acceleration profile indicating person jumped
AIM Detected temporary raising of gun, toggles AIM state, reversal also detected
MOVX Simulate movement in the X direction
MOVY Simulate movement in the Y direction
I2c Related I/O (if ultimately we decide to connect):
NAME PIN Purpose in Accelerometer
---- --- -----------------------------------------------
INTA 24 Need to look up
INTB 26 Need to look up
PWM Device Reference:
NAME Description
---- -------------------------------------------------
RJYX X axis of the right joystick
RJYY Y axis of the right joystick
LTRG Left trigger
RTRG Right trigger
Mapping overview:
The following inputs and internally generated events constitute all the items that need to be mapped: RLOD,
THMB, LIDX, TOPA, PINK, RING, GRIP, JUMP, AIM, MOVX, and MOVY. There are 11 in total. 2 of these are
restricted to PWM outputs because they produce varying values (MOVX, MOVY).
The following outputs exist X, Y, A, B, LB, RB, LSTK, <, RJYX, RJYY, LTRG, and RTRG. There are a total of
12, 4 of which are PWM outputs (which we'll call analog for purposes of differentiating them from switch
signals). The MOVX and MOVY are likewise called analog inputs so can only be mapped to analog outputs.
Digital inputs can however be mapped to analog outputs - this is done by outputting the maximum value.
Software shall validate the mapping is complete. There is one more output than input because the right
stick down feature currently is not used - as I'm aware anyway, but this is a future enhancement to
consider. Validation ensures all 11 inputs are mapped, Analog maps only to analog, no repeated mapping
assignments (all unique).
Accelerometer Discussion:
I think that when the gun is in use there may actually be more events generated via interrupt than if you
simply implemented a polling scheme leading to non-deterministic behavior. Probably best to remove the
interrupt tracking and free up pins 24/26.
Architecture:
Device Drivers -
PWM Driver - Generic ability to turn on/off a "value" on a specific device for a specific amount of
time. Will control 4 PWM devices (X-Right Stick, Y-Right Stick, Right Trigger, Left Trigger)
AM Driver - Talks to the accelerometer and regularly polls it for delta changes in G's pulled in all
AXIS directions (X - left/right, Y - Up/Down, Z- Forward/Backwards). If an identified threshold is exceeded
then it outputs an event indicating how much it moved (percent of max G) over what period of time in each of
the axis. The driver also looks for JUMP and AIM profiles. Aim profile will generate a toggling event
indicating the current state (allowing receiver to toggle it as well). Jump is simply an single event with
no state tracking. A Jump is profiled by looking for significant G's pulled in the -Y direction. AIM is
detected with a smaller -Y but more consistent pulled over a longer period of time (say 1/2 second as
opposed to a big pulse for a jump).
Digital I/O - This driver accepts the mapping file as input as well as a software interface for
events. The following Pins will be configured as inputs: 7 (GPIO_04), 8 (GPIO_14), 10 (GPIO_15), 24
(GPIO_08), 11 (GPIO_17), 12 (GPIO_18), 13 (GPIO_27). The following pins will be configured as outputs:
15 (GPIO_22), 16 (GPIO_23), 18 (GPIO_24), 19 (GPIO_10), 21 (GPIO_09), 22 (GPIO_25), 23 (GPIO_11), 26
(GPIO_07). The driver is interrupt driven on all of the input pins. When an input is triggered (rising
edge, trailing edge) - it immediately triggers is "partnered" ouput. If that output is an analog mapped
device (PWM) then it generates an event for it. The driver also accepts software inputs to turn on/off
outputs that are mapped that way. Inputs that trigger with a non-digital output mapped (or no output
mapped) are forwarded as events to the main input event handler. The driver will also allow the application
to define "Combo events" which get sent when multiple input lines are "ON" simultaneously.
Glue Logic -
3D to 2D mapping - The accelerometer outputs events that indicate movement in 3D space based on
percentage of max G's pulled in each direction. This information must be converted to movement of the
Joystick which is a 2 axis device. The conversion is done and the PWM driver is told what to do based on
the data (mapping file consulted on which PWM device as well).
Input Event handler - Discrete events can be triggered without a digital output mapped (like the
main trigger button). Software events can also be received detecting a JUMP, or AIM condition. The IEH's
job is to turn these events into actions - typically by mapping them to the appropriate PWM device.
Administration -
Calibration - it is anticipated that we might need to calibrate movement, and jump/aim detection. A
process for doing this needs to be triggered via a button. It will be triggerd via a defined "Combo" event
requiring that the following inputs be ON: TRIG, TOPA
Properties - Will be in the code because arduino won't have a file system.
Detailed Design:
The ultimate production goal with this device would be to migrate to a more efficient microcontroller that
doesn't have all the RPi overhead (linux, HDMI, ethernet, devices, etc). All we need is a good I/O device
that can do some fairly simple math. But in the end an RPi is very convenient as a test platform. It is
important that we don't finish the prototype software just to find out that we have to re-invent it because
you couldn't put it on an arduino. Thus we should go into this assuming that we will be limited to what is
available on Arduino (no linux, no use of sockets, no file system, no QT or other libraries that aren't
available in the Arduino world, no IPC, no multi-threading). Basically anything complex I'll need to invent
and every IO function needs to mimic the arduino API so I don't have to rework things later on:
arduino.cc/en/Reference/HomePage
Much that we have to do manually in the RPi world just works in the Arduino world (DIO, PWM, etc). Luckily
it seems that the Gordon fellow I got the wiringPi library from actually emulated the arduino functions:
projects.drogon.net/raspberry-pi/wiringpi/
DO NOT USING MULTI-THREADING. Its not possible in the arduino world.
namespace - ITC
PWMDriver class
AMDriver class
DIODriver class
3D2DMapping class
EventHandler class
Calibration class
Properties class