modules - marcosassis/gamepaduino GitHub Wiki

gamepad library modules and dependencies

each dependency is described on it's respective module. this pages details license terms and lists everything needed to go full load.


todo: insert picture

(some titles are also links. please inform me if something is broken on wiki)

list of modules

gamepad library

general obligatory dependencies: none

default turn on:

  • multiplayer functionality

    • examples -> gamepad -> *_multiplayer
    • very easy to turn off
      • (see examples with *_singleplayer)
    • depends on this [minimalist] external module: LinkedList
    • max number of players is not limited by this class, but by each specific protocol and modules used

retro game controllers/gamepads interfaces implementations

  • N64 controllers

    • examples -> gamepad -> N64_*
    • singleplayer and multiplayer N64 protocol implementation and interface
      • requires: AVR running at 16MHz
      • pins available:
        • [advanced]:
          • any usable pin mapped to ATmega's PD register
            • (one day we can generalize this for other registers)
        • pro micro board:
          • arduino/DIO pins {2,3,4,6}
            • so, max number that 1 pro micro can drive is 4 N64_gamepad's, for now

              • [tested 2 simultaneously]

        • general arduino boards:
          • arduino/DIO pins {0,1,2,3,4,5,6,7}
            • in general arduino boards, digital pins 0..7 correspond to PD bits 0..7

  • SNES controllers

    • examples -> gamepad -> SNES_*
    • singleplayer and multiplayer SNES protocol implementation and interface
      • requires: arduino-compatible
      • pins available: any DIO
        • so, max number of players on 1 board is theoretically unlimited by gamepad library, in this sense

cool [new] output capabilities for your [retro] gamepads

out-of-the-box adapters

  • turn your board into an USB HID gamepad/joystick

    • gamepad_joystick_adapter module
      • examples -> gamepad -> with *_usb_hid
      • this is optional, you don't have to include this nor download ArduinoJoystickLibrary if you don't want/can't to go USB
      • depends on this nice external module: ArduinoJoystickLibrary
        • see supported boards of this library
        • available gamepad IDs
          • for gamepad_joystick objects (also SNES_hid and N64_hid include in this file):
          • IDs: {1,2,3,4}
            • this turns on USB/HID IDs as hidReportId=gamepadobj.id+2
            • so if you're plugging different boards on same computer with same IDs, they'll conflict

todo: UML models (or any other suggestion?)

full load, no sh*cheat

this is just a download-link list, see other instructions on wiki if you feel noob.

download and install:

  • gamepad
  • LinkedList
    • dependency for functionality: multiplayer
      • this is turn on by default
      • (see details below on how to turn off this you you only have 1 gamepad)
  • ArduinoJoystickLibrary
    • dependency for module: gamepad_joystick_adapter
    • install this if your chip is USB enabled
      • an adaptor for this library is provided, so you can turn your ATmega32U4 based board (such as pro micro or leonardo) into a USB HID device class gamepad/joystik (that's: plug&play on any computer)
      • this is optional, you only have to include if you want to go USB (but of course.)
  • MIDIUSB
    • adaptor + MIDI structured interface is in development
  • open examples.

put all stuff working

these are the main wiki pages:

but see also other wiki stuff on pages menu (on the right-up)).

if you are wondering now 'why am i here?' because you don't have an USB enabled board (or you have, anyway), please see these considerations.

if you want to understand more in anyway gamepad library, please also refer to these same considerations.

general

you have great functionality out-of-the-box with gamepad library bare-bones, such as physical interfaces with oldschool gamepads [for now we have nice working N64 and SNES controllers interfaces, both multiplayer].

but with some third party libraries† the game goes crazy!! as an example, if you install ArduinoJoystickLibrary, you can open examples -> gamepad -> *_usb_multiplayer (N64 and SNES out-of-the box) and that is it. with very few lines of code, some wiring [no, please don't cut these precious relics] and an emulator, just that, and you'll probably have a great experience already. and most important: you can mod everything! it's not another cheap industrial-closed product faded to obsolescence, it's a dynamic thing, a hardware that you can program (easily).

and this is cool and true not so only for USB enabled boards, since communication with gamepads doesn't require USB capabilities =] (you know, this kind of message is for noobs)

(but some of them may have its own requirements, see for e.g..)

so, specifically, right now out-of-the-box with-or-without USB:

  • you can use the great buttonset, gamepad, bit_gamepad interfaces to access the state and information about your N64_gamepad and SNES_gamepad
    • you can even access directional interface (coherently) through gamepad::get_dpad(uint8_t i=0)
      • SNES_gamepadhas 1 dpad
      • N64_gamepad has 2: Dpad(did=0) and Cpad(did=1)
    • soon analog interface (available on N64) will be generic

just create object and call read() on loop

(this is a mantra about this library.)

soon [todo more] specific examples about how to use these methods in loop, but you can see these respective files and hope it'll be really easy to understand how to query about button state or changing. (hey, it's in progress, look at examples with *_loop for how to print your (any) controller on loop and begin to familiarize yourself with gamepad library)

there's also a totally experimental USB MIDI output/interface (also as an out-of-the-box controller->MIDI commands adapter for both [multiplayer] SNES and N64 gamepads) going on. (with N64 analog stick we can pitch-bend...). i'm calling this kind of thing x-area now, be warned, it's absurdly cool but work in progress

latency that is perceptible is not acceptable.

thanks

this library, specially the physical interfaces, is also thanks to many references found online: I just re-wrote the codes (by following protocol descriptions/pseudo-code, other arduino codes and other sources), some nice people did all the job of reverse engineering all these things. and then come all this knowledge collectively build along many cycles of collaborations, code writings and re-writings, projects and tutorials spread along the web. thank you very much.

if you're not feeling so noob

† and: how about your own interface for gamepad library!? if you're interested, please tell me, sure we can collaborate. the idea is that with a nice unique interface, it'll be easier and pleasanter to make other protocols, so to be used the same way.


todo: take and include photos / nice media

multiplayer module/functionality

multiplayer is turn on by default.

this is how to turn out (really easy).

it depends only on this external module:

  • LinkedList: see details below

LinkedList

for multiplayer functionality, you have to download&install LinkedList and agree to LinkedList's license terms, which is MIT License:

A short and simple permissive license with conditions only requiring preservation of copyright and license notices. Licensed works, modifications, and larger works may be distributed under different terms and without source code.

LinkedList file is included internally on multiplayer class, so just install it and use the concrete multiplayer classes provided with library ([adv] or do your own, for your gamepad). this library is super light and this data structured is just essential.

how to opt-out multiplayer (and LinkedList dependency):

  • to opt-out (turn off, don't compile neither include) multiplayer functionality throughout gamepad library you have to define _GAMEPAD_SINGLEPLAYER before include gamepad files, as exampled in *_gamepad_usb_single.h files.

todo: include multiplayer photos

gamepad_joystick_adapter module

this is optional, you don't have to include gamepad_joystick_adapter.h(that includes Joystick.h) nor download ArduinoJoystickLibrary if you don't want to go USB.

each different gamepad model should have its concrete adaptor, so user can just plug their gamepad to their board and are ready-to-play retro games on computer. see N64 and SNES examples (more to come / please contribute).

gamepad_joystick template class is an adaptor project pattern class created to allow use gamepad library's structured interface in conjunct with functionality provided by:

  • ArduinoJoystickLibrary: library is included internally, do more nothing, just use this adaptor class or derivatives. see details below

ArduinoJoystickLibrary

... so, you have to download&install it and agree to ArduinoJoystickLibrary's license terms, which is GNU Lesser General Public License v3.0:

Permissions of this copyleft license are conditioned on making available complete source code of licensed works and modifications under the same license or the GNU GPLv3. Copyright and license notices must be preserved. Contributors provide an express grant of patent rights. However, a larger work using the licensed work through interfaces provided by the licensed work may be distributed under different terms and without source code for the larger work.


todo: include photo