{"id":36590791,"url":"https://github.com/reallyinsane/trainsimulator-controller","last_synced_at":"2026-01-12T08:14:16.116Z","repository":{"id":53191671,"uuid":"90663189","full_name":"reallyinsane/trainsimulator-controller","owner":"reallyinsane","description":"Control the controls of your locomotive in TrainSimulator and e.g. bind your own hardware using a REST or Java API.","archived":false,"fork":false,"pushed_at":"2025-01-19T10:32:00.000Z","size":27067,"stargazers_count":7,"open_issues_count":2,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-01-19T11:27:24.959Z","etag":null,"topics":["game-development","java","trainsim"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/reallyinsane.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-05-08T19:08:08.000Z","updated_at":"2025-01-19T10:32:02.000Z","dependencies_parsed_at":"2022-09-14T18:02:02.878Z","dependency_job_id":null,"html_url":"https://github.com/reallyinsane/trainsimulator-controller","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/reallyinsane/trainsimulator-controller","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reallyinsane%2Ftrainsimulator-controller","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reallyinsane%2Ftrainsimulator-controller/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reallyinsane%2Ftrainsimulator-controller/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reallyinsane%2Ftrainsimulator-controller/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/reallyinsane","download_url":"https://codeload.github.com/reallyinsane/trainsimulator-controller/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reallyinsane%2Ftrainsimulator-controller/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28337410,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-12T06:09:07.588Z","status":"ssl_error","status_checked_at":"2026-01-12T06:05:18.301Z","response_time":98,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: 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":["game-development","java","trainsim"],"created_at":"2026-01-12T08:14:14.302Z","updated_at":"2026-01-12T08:14:16.111Z","avatar_url":"https://github.com/reallyinsane.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Build Status](https://travis-ci.org/reallyinsane/trainsimulator-controller.svg?branch=master)](https://travis-ci.org/reallyinsane/trainsimulator-controller)\n[![Codacy Badge](https://api.codacy.com/project/badge/Grade/6b11f46bd5f34e3ba4c91e96b7ccf99c)](https://www.codacy.com/app/reallyinsane/trainsimulator-controller?utm_source=github.com\u0026amp;utm_medium=referral\u0026amp;utm_content=reallyinsane/trainsimulator-controller\u0026amp;utm_campaign=Badge_Grade)\n\u003ca href=\"https://opensource.org/licenses/Apache-2.0\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-apache2-blue.svg\"\u003e\u003c/a\u003e\n\n# TrainSimulator Controller\n\nThis project was created to use custom controls as input or output while playing TrainSimulator. Especially when activating Sifa and PZB direct interaction is needed as soon as this is indicated by\nthe game. But not in all situations (e.g. camera position) the regarding controls are visible.  So the idea was, having custom controls outside of the game.\n \n TrainSimulator offers an API to interact with the game and get status of any control provided by the driven locomotive. It is also possible to send control changes to the game, e.g. indicating that\n PZB vigilance has been pressed. So you can use this API to communicate with custom input/output controls.\n \n## Project structure\n\nThe API provided by TrainSimulator is available by a Windows DLL only and thus can be accessed on the host only. To be able to access the API also from other clients (e.g. a Raspberry PI or Arduino)\na service had to be established. The current project offers a server part with this logic, a client part accessing this service and two sample clients using a Raspberry PI and a FT232h controller.\n\n|module                   |description                                                                            |\n|-------------------------|---------------------------------------------------------------------------------------|\n|trainsimulator-client    | Client component which can access the REST service provided by trainsimulator-server. |\n|trainsimulator-core      | Domain classed used by client and server modules.                                     |\n|trainsimulator-ft232h    | Sample client for a FT232h controller used as USB device on the host.                 |\n|trainsimulator-parent    | Infrastructure module managing dependencies.                                          |\n|trainsimulator-raspberry | Sample client for Raspberry using the service over LAN/WLAN.                          |\n|trainsimulator-server    | Server component providing REST service on host.                                      |\n\n## trainsimulator-server\n\nThe server module provides a REST service with all functions to interact with TrainSimulator API. It's a Spring Boot application which can be started as fat jar. By default the service will be started \non port 13913. The REST service provides the following methods:\n\n|method |path                              |description                                                          |\n|-------|----------------------------------|---------------------------------------------------------------------|\n|GET    |/trainsimulator/locomotive        | Information about the current engine with their supported controls. |\n|GET    |/trainsimulator/generic           | Information about the current engine in plain format.               |\n|GET    |/trainsimulator/control/{control} | Get value of single control with min, max and current.              |\n|PUT    |/trainsimulator/control/{control} | Change value of a single control.                                   |\n\nUsing the REST service is one way to interact with TrainSimulator API. Another way is to extend the trainsimulator-server application. For handling changes of a control's value an \nannotated method can be used. Just declare a spring component with a method with io.mathan.trainsimulator.service.Present annotation. This methods accepts a parameter of type\nio.mathan.trainsimulator.service.Event and is called each time a control's value changes. (The check is scheduled each 100ms) \n\n```\n@Present\npublic void present(Event event) {\n  Control control = event.getControl();\n  ControlData data = event.getData();\n}\n```\nBy this you can manage output controls. To manage input controls you have to send events to a trainsimulator-server component. This can be done by having a spring component with the\nio.mathan.trainsimulator.service.Collector component injected. If an input control should fire an event the method Collector.raiseEvent(Event) should be used.\n\n```\n@Component\npublic class CustomInputControl {\n  private Collector collector;\n  public void someMethod() {\n    ...\n    Control control;\n    ControlData data;\n    Event event = new Event(control, data);\n    collector.raiseEvent(event);\n  }\n}\n``` \n\nThe REST service itself is using both approaches to publish control changes received through the REST call to TrainSimulator and acts as receiver of control changes. These are cached for the REST \ncalls.\n\n### Supported controls\n\nThere are various controls supported by TrainSimulator. It depends on the selected engine which controls are available. There are also differences in naming of the controls. For a generic API an\ndefined enum is used to identify the controls.\n In general the API can be used to either display the current/minimum/maximum value of a control and to change the value of a control, e.g. for resetting the VigilAlarm or change the throttle.\n\nThe following controls are supported (although there are different names for the controls in different engines, the names chosen are the common used):\n\n- Vigil controls\n    - VigilEnable\n    - VigilLight\n    - VigilAlarm\n    - VigilReset\n- PZB controls\n    - PZBEnable\n    - PZB_55\n    - PZB_70\n    - PZB_85\n    - PZB_40\n    - PZB_500\n    - PZB_1000\n    - PzbWarning\n    - Cmd_40\n    - Cmd_Free\n    - Cmd_Wachsam   \n\n### Support for additional locomotives \n\nThe controls above are some of the major controls when using vigil or PZB. The name of the control in TrainSimulator depends on the vendor of the product. It is not the same for all locomotives.\nTherefore mappings can be defined if the name of the control does not match the control name above. There are already some default mappings for some of the locomotives I used.\n\nPlease see [default.mapping](./trainsimulator-server/src/main/resources/default.mapping) for details.\n\n### Sample trainsimulator-ft232h (second version)\n\nThe description of the first version using ft232h can be found in the next chapter. After that I created a second version with more functionality. It is using a Adafruit FT232h breakout as USB decive\ntoo. But this time more devices are connected using I2C protocol. I used:\n\n- 1 x \"PZB-Würfel\"\n- 2 x [MCP23017] for GPIO (GPIOs of [FT232h] cannot be used as I2C is required for other devices)\n- 3 x [Sparkfun 4 digit 7 segment] in white, red and blue\n- 1 x [Adafruit bargraph] with 24 segments green/yellow/red\n- 1 x [LED stripe]\n- 2 x On/On Switches (as input)\n- 2 x Buzzer\n\nWith this sample project I can show all pzb controls, sifa light the LZB distance (\u003c1000m red, \u003c4000m yellow, \u003e4000m green) and numbers/time on the three 4 digit displays. Currently I implemented:\n- showing time (scenario time)\n- showing LZB distance in meters\n- showing LZB speed (Vsoll which is maximum speed allowed in current section, Vziel which is maximum speed allowed in next section)\n- showing AFB target speed\n- showing current speed\n\n\u003cimg src=\"https://raw.githubusercontent.com/reallyinsane/trainsimulator-controller/master/device.jpg\" width=\"200px\"\u003e\n\u003cimg src=\"https://raw.githubusercontent.com/reallyinsane/trainsimulator-controller/master/device_pzb_1.jpg\" width=\"200px\"\u003e\n\u003cimg src=\"https://raw.githubusercontent.com/reallyinsane/trainsimulator-controller/master/device_pzb_2.jpg\" width=\"200px\"\u003e\n\u003cimg src=\"https://raw.githubusercontent.com/reallyinsane/trainsimulator-controller/master/device_speed.jpg\" width=\"200px\"\u003e\n\u003cimg src=\"https://raw.githubusercontent.com/reallyinsane/trainsimulator-controller/master/device_time.jpg\" width=\"200px\"\u003e\n\u003cimg src=\"https://raw.githubusercontent.com/reallyinsane/trainsimulator-controller/master/device_lzb.jpg\" width=\"200px\"\u003e\n\n\n### Sample trainsimulator-ft232h (first version)\n\nThis sample project adds a Adafruit FT232h breakout as USB devices to the host and sends the control data using GPIO. Therefore trainsimulator-ft232h extends the Spring Boot application of\ntrainsimulator-server by registering an additional component to receive events that sent to the FT232h. \n\nTo be able to connect controls (the sample supports output controls only) you have to provide a configuration file `application.properties` in the same folder as the JAR of the spring boot application. \nIn this file the mapping is made between the control and the GPIO pin to use. By default the file looks like this:\n\n```\n# needed to activate spring component to connect to ft232h\nspring.profiles.active=production,pzb\n# important for additional clients or when accessing REST service through browser\nserver.port=13913\npzb.pzb55=C0\npzb.pzb70=C1\npzb.pzb85=C2\npzb.pzb40=C3\npzb.pzb500=C4\npzb.pzb1000=C5\npzb.sifaLight=D1\npzb.sifaWarn=C6\n```\n\nThis sample supports the following properties:\n- `pzb.pzb55`\n- `pzb.pzb70`\n- `pzb.pzb85`\n- `pzb.pzb40`\n- `pzb.pzb500`\n- `pzb.pzb1000`\n- `pzb.sifaLight`\n- `pzb.sifaWarn`\n\nAs values you can use C0-C7 and D0-D7.\n\n\nRequirements:\n- Hardware:\n    - [Adafruit FT232h Breakout](https://www.amazon.de/Adafruit-FT232H-Breakout-General-Purpose/dp/B00XW2MD30)\n    - LEDs \n- Software:\n    - [D2XX Drivers](https://www.ftdichip.com/Drivers/D2XX.htm)\n \n\u003cimg src=\"https://raw.githubusercontent.com/reallyinsane/trainsimulator-controller/master/ft232h_front.jpg\" width=\"200px\"\u003e\n\u003cimg src=\"https://raw.githubusercontent.com/reallyinsane/trainsimulator-controller/master/ft232h_back.jpg\" width=\"200px\"\u003e\n\n[FT232h]: https://www.amazon.de/Adafruit-FT232H-Breakout-General-Purpose/dp/B00XW2MD30\n[MCP23017]: https://www.microchip.com/wwwproducts/en/MCP23017\n[Sparkfun 4 digit 7 segment]: https://www.sparkfun.com/products/11441\n[Adafruit bargraph]: https://www.adafruit.com/product/1721\n[LED stripe]: https://www.amazon.de/gp/product/B071KBY7NW/ref=ox_sc_act_title_2?smid=AQ1IBDB6G2RRD\u0026psc=1\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Freallyinsane%2Ftrainsimulator-controller","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Freallyinsane%2Ftrainsimulator-controller","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Freallyinsane%2Ftrainsimulator-controller/lists"}