{"id":20566417,"url":"https://github.com/hean01/acb","last_synced_at":"2026-04-22T10:02:33.347Z","repository":{"id":146334457,"uuid":"117910269","full_name":"hean01/acb","owner":"hean01","description":"Arcade controller board, a project for a minimalistic I2C arcade controller board for use with Raspberry Pi and similar.","archived":false,"fork":false,"pushed_at":"2018-01-21T18:37:26.000Z","size":990,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-06T08:57:55.383Z","etag":null,"topics":["arcade-controller","arcade-machine","raspberry-pi","raspberry-pi-3","retrogaming"],"latest_commit_sha":null,"homepage":null,"language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hean01.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-01-18T00:37:09.000Z","updated_at":"2019-01-10T16:09:40.000Z","dependencies_parsed_at":"2023-05-17T08:42:00.376Z","dependency_job_id":null,"html_url":"https://github.com/hean01/acb","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/hean01/acb","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hean01%2Facb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hean01%2Facb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hean01%2Facb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hean01%2Facb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hean01","download_url":"https://codeload.github.com/hean01/acb/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hean01%2Facb/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32130776,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-22T08:34:57.708Z","status":"ssl_error","status_checked_at":"2026-04-22T08:34:55.583Z","response_time":58,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["arcade-controller","arcade-machine","raspberry-pi","raspberry-pi-3","retrogaming"],"created_at":"2024-11-16T04:41:41.835Z","updated_at":"2026-04-22T10:02:33.288Z","avatar_url":"https://github.com/hean01.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Arcade controller board\n\nThis project consist of schematics and a linux kernel driver module\nfor a controller board used for building an Arcade machine. The board\nis easily build on a strip-board with minimal components and costs.\n\nThe requirement for using the _arcade controller board_ is that you\nhave an hardware platform with 5V, I2C bus to chain your board on and\na gpio pin available for each board you hook up, used for interrupt\ndriven input. With other words, a normal computer is not working and\nyou need to look into hardware of the Raspberry Pi era that meets\nspecified hardware requirements.\n\nThree boards are needed for a two player setup cabinet and two boards\nfor a single player configuration. The design of the _arcade\ncontroller board_ allows a maximum of 7 boards to be connected to the\nI2C bus. This means a maximum of 112 individual inputs and allows for\nany imaginable cabinet build as long that you have 7 gpio pins\navailable for allocation.\n\nConceptually, there are two types of controller boards _player_ and\n_auxiliary_. You need at least one player and one _auxiliary_\ncontroller for a single player setup, you can skip the _auxiliary_ but\nhow fun is that. The actual hardware used for the two types of\ncontroller boards does not differ, they are both design the same way\nand specifying a type is just a matter of a software configuration.\n\nThe differences are that the _player_ controller board will provide 16\nindividual inputs for the player this is more than enough for game\nplay of most arcade and consoles. The _auxiliary_ controller board\nwill provide additional 8 individual inputs used for generic input for\nexample special emulator commands etc. and 8 generic outputs which you\ncan use for steering hardware in your cabinet build.\n\nThis project provides an Linux kernel module with the driver for the\ntwo types of boards and some parameters to define which board is of\nwhat type. The type mapping is done by the configurable I2C address\nusing jumpers on the _arcade controller board_.\n\nWhen you load the Linux kernel driver module, it will try to\ninstantiate three instances of the driver, two _player_ and one\n_auxiliary_ instance. Each instance creates and evdev input device for\nuse with the Linux input system that is then mapped and used by the\nemulator of your choice.\n\nThe special _auxiliary_ board will also create and evdev input device\nwith eight buttons. The 8 outputs of an _auxiliary_ board is exported\ninto sysfs to be controlled from software or scripts. Use it as you\nsee fits, for example turn on / off marque lights or what not.\n\n\n## Building the board\n\n_Arcade controller board_ is built around MCP23017 I2C I/O expander\nchip and is very simple to build on a strip board.\n\nEach board is connected to a I2C bus and a gpio pin used for interrupt\nwhen any input changes. You will use jumpers to set the I2C address of\nthe board which is used by the Linux kernel driver to detect which\ntype of board to instantiate. You can provide module parameters when\nloading the Linux kernel module driver to specify which address and\ngpio pin to use for each board types. Read section\n[Using the Linux kernel module](#using-the-linux-kernel-module) for\nmore details how to use the module.\n\nThe image below shows how to build one using strip board, it is also\nmarked up of which I/O pin that is mapped to input device event by the\ndriver for reference when hooking up the board with your hardware.\n\n![Arcade controller board layout](doc/arcade_controller_board.png)\n\nThe result of a built _arcade controller board_ of above layout looks\nlike the following image. However you could with some ease actually\nbuild three copies of the board into a hat design to sit on top of a\nRaspberry Pi. Its a matter of taste really, however I will not provide\nany hardware specific designs in this project.\n\n![Built version of the board](doc/arcade_controller_board_build.png)\n\nAs the built example above, you will see that this is very\nminimalistic and clean build, anyone could do it.\n\n\n### Hook up guide of Arcade joystic and buttons\n\nEach input on the board should short with ground to generate an\nevent. A typical build is that you make an daisy chain of the the\nground through your switches and then hook up the individual gpio pin\nwith corresponding switch described in the strip-board schematics\nabove.\n\nFor my setup I choose the following standar layouts for the two player\ncontrollers, first one is Player 1 setup, the left side of cabinet and\nthe second if for Player 2, right side. This is just for ideas and\nreference, use any layout that fits your needs.\n\n![Player 1 layout panel layout](doc/sega1_l.png)\n![Player 2 layout panel layout](doc/sega2_l.png)\n\n\n### Hook up with Raspberry Pi 3\n\nMy initial choice of emulation platform is the Raspberry Pi 3 and\ntherefor I will also describe how to hook up the boards with this\nspecific device.\n\nHere follows a diagram for the pin header of Raspberry Pi 3. The pins\nlabled SDA1 / SCL1 is used for the I2C bus, and all your _arcade\ncontroller boards_ should be connected in parallel on those two pins,\n5v and ground. Each board will also allocate a individual gpio pin\nused for interrupts which is also labled in diagram below.\n\nHere follows the pin header layout for Raspberry Pi 3 and the pins you\nwill hook up the board to:\n\n\t       .---.\n\t       |[]o| 5v\n\t  SDA1 |o o| 5v\n\t  SCL1 |o o| Ground\n\t       |o o|\n\t       |o o|\n\tGPIO17 |o o|\n\tGPIO27 |o o|\n\tGPIO22 |o o|\n\t       .   .\n\n\t       .   .\n\nDefault settings for the Linux kernel driver is targeted the Raspberry\nPi 3 and if your configure your boards and hook as described below, it\nwill work just right out of the box.\n\n- Player 1, I2C Address: 0x20, Interrupt: GPIO17\n- Player 2, I2C Address: 0x21, Interrupt: GPIO27\n- Auxiliary, I2C Address: 0x22, Interrupt: GPIO22\n\nIf you want to use other addresses or gpio pins, you can change this\nusing module parameters. This is needed for other hardware platforms\nthat is not Raspberry Pi 3 compatilble. Read more about how to do this\nin section\n[Using the Linux kernel module](#using-the-linux-kernel-module).\n\n\n## Using the Linux kernel module\n\nThe driver is loaded using insmod or adding the module for automatic\nload upon startup, this is distribution specific and I will not go\ninto details.\n\n\tinsmod src/acb.ko boards=\"player:0x20:17\",\"player:0x21:27\",\"auxiliary:0x22:22\"\n\nAs you noticed the above command describes each board with type and\nwhich I2C addresses and gpio pin numbers to be used. Those values\nabove is the default and can be left out if you are using Raspberry Pi\nand hooking up the boards as described in section\n[Hook up with Raspberry Pi 3](#hook-up-with-raspberry-pi-3).\n\n\n### Building the driver\n\nTo build the Linux kernel module driver you need to install the kernel\nsource package for your distribution, then just build the module using:\n\n\tmake\n\nThis will build the kernel module `src/acb.ko` for your current\nkernel. If you upgrade the kernel the module might need to be rebuilt\nto work as expected, this is identified by error messages in dmesg log\nwhile loading the module.\n\n## Configuration of emulators\n\n### Retroarch\n\nRetroarch uses controller specific configuration files. These files\nmaps input events to retroarch buttons and exists in\n`/usr/share/retroarch/autoconfig/udev/`. You need to create two\nconfiguration files one for _player_ and one for _auxiliary_ and here\nfollows the examples configuration files.\n\n/usr/share/retroarch/autoconfig/udev/acb_player.cfg\n\n\tinput_device = \"Arcade player controller\"\n\tinput_driver = \"udev\"\n\n\tinput_b_btn = \"1\"\n\tinput_y_btn = \"3\"\n\tinput_select_btn = \"6\"\n\tinput_start_btn = \"7\"\n\tinput_up_axis = \"-1\"\n\tinput_down_axis = \"+1\"\n\tinput_left_axis = \"-0\"\n\tinput_right_axis = \"+0\"\n\tinput_a_btn = \"0\"\n\tinput_x_btn = \"2\"\n\tinput_l_btn = \"4\"\n\tinput_r_btn = \"5\"\n\n\n/usr/share/retroarch/autoconfig/udev/acb_auxiliary.cfg\n\n\tinput_device = \"Arcade auxiliary controller\"\n\tinput_driver = \"udev\"\n\n\tinput_save_state_btn = \"0\"\n\tinput_load_state_btn = \"1\"\n\tinput_exit_emulator_btn = \"2\"\n\tinput_reset_btn = \"3\"\n\tinput_menu_toggle_btn = \"4\"\n\tinput_enable_hotkey_btn = \"5\"\n\tinput_pause_toggle = \"6\"\n\n\n## Troubleshooting\n\n\n### Connectivity\n\n1. Verify that expected boards are instantiated correctly using the\n   tool `evtest`, which shows a list of registered input devices one\n   for each board. Verify that the list contains expected input\n   controllers, names to look for are `Arcade player controller` and\n   `Arcade auxiliary controller`. Then select one of them and test the\n   controller inputs.\n\n\t\tevtest\n\n2. If controller shows up in step 1, and nothing happens when testing\n   the controllers, verify that you are using the correct gpio pin for\n   input interrupt.\n\n3. There are some minor logging when the Linux kernel module is\n   loaded. Check the that there are no errors while loading the module\n   using dmesg.\n\n4. Probe the I2C bus for available devices and verify that your boards\n   are found using the following tool. If no devices are found, probe\n   other buses to find the correct one on you system:\n\n\t\ti2cdetect -y 1\n\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhean01%2Facb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhean01%2Facb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhean01%2Facb/lists"}