ETCARS Documentation Release 0.14
Total Page:16
File Type:pdf, Size:1020Kb
ETCARS Documentation Release 0.14 Josh Menzel Apr 06, 2019 Contents 1 Introduction 1 1.1 General..................................................1 1.2 Built With................................................1 1.3 Contributors...............................................1 1.4 License..................................................2 2 Getting Started 3 2.1 Windows.................................................3 2.2 Linux...................................................4 2.3 Mac OS X................................................4 2.4 Additional Information..........................................4 3 Receiving Data 5 3.1 Putty...................................................5 3.2 Programming...............................................5 3.3 Third Party Packages...........................................6 4 The Data 7 4.1 General..................................................7 4.2 SDK Events...............................................7 4.3 Events..................................................8 4.4 Structures................................................. 10 i ii CHAPTER 1 Introduction 1.1 General ETCARS is an open source telemetry implementation for American Truck Simulator and Euro Truck Simulator 2 created by SCS Software. ETCARS stands for Electronic Truck Communications Addressing and Reporting System. It is built using c++ and officially compatible with Linux and Windows, with the potential to be built on Mac OS X. ETCARS runs a local TCP Socket Server on the computer running the game. This allows for data to be broadcast to any clients that wish to connect. Starting with version 0.14, ETCARS will only have 64-bit support. This is due to the issues encountered when trying to build for 32-bit platforms. 1.2 Built With ETCARS is built with several other libraries: • Boost C++ 1.66 • CryptoPP(Crypto++) • Rapidjson • OpenSSL • cURL • Steamworks • SCS SDK 1.3 Contributors Contributors can be found on the Gitlab repository. 1 ETCARS Documentation, Release 0.14 1.4 License This software is licensed under the GNU GPL v3.0 License. 2 Chapter 1. Introduction CHAPTER 2 Getting Started 2.1 Windows To install ETCARS on Windows, there are some prerequisites to installing: • Valid OS • American Truck Simulator and/or Euro Truck Simulator 2 (Steam Linked) • Microsoft Visual C++ Redistributable 2017 2.1.1 Supported Windows Versions The following Windows Versions are supported: • Windows 7 x64 • Windows 8 x64 • Windows 8.1 x64 • Windows 10 x64 2.1.2 Microsoft Visual C++ Redistributable 2017 The Microsoft Visual C++ Redistributable 2017 is a dependency for the plugin to function properly in the Windwos environment. For 64-bit users, you’ll need to install both the 32-bit(x86) and 64-bit(x64) version of the redistributable. They can be downloaded using the links below: • x86 • x64 3 ETCARS Documentation, Release 0.14 2.1.3 Installing Once the Microsoft Visual C++ Redistributable 2017 has been installed, you can now proceed to installing ETCARS! To install ETCARS, simply download one of the installers from the ETCARS website at https://etcars.menzelstudios. com. Then run the installer and boom! You’re all set to go! 2.2 Linux To install the latest version of ETCARS on linux, open a terminal window in a directory you have write access to. Then download the installation script by pasting the following line into the terminal window, then press enter. wget https://gitlab.com/jammerxd/ETCARS/blob/master/ETCARS/install_etcars_linux.sh The installation script will use wget to download 2 files. One is the shared object plugin, the other is a file used by cURL. To run the installation script, execute the following by copying and pasting the following line into the terminal window and pressing enter. bash install_etcars_linux.sh Congratulations! ETCARS is now installed and will run when your game runs! 2.3 Mac OS X To install on Mac OS X, you’ll need to download the Mac version of ETCARS and place it in the plugins folder of the eurotrucks2 executable. This is found by finding “Euro Truck Simulator 2” but instead of launching, right-click and click on “Show Package Contents”. Then go into Contents->MacOS and create a plugins folder if not already existing and place the ETCARS plugin file in the plugins folder. This will allow the game to load ETCARS. The last step is to download the curl certificate bundle: cacert.pem and place it in your Documents/ETCARS folder(creating it if it doesn’t already exist). See additional information below for reasons why this needs to be done. 2.4 Additional Information The current install script is set to install the 64-bit edition ONLY. | | NOTE: ETCARS uses a certificate bundle for host verification. The file ca-certificates.crt can be downlocaded from the cURL web site as cacert.pem and then renamed to ca-certificates.crt and placed in /etc/ssl/certs/. This is required for cURL and ETCARS to work correctly. 4 Chapter 2. Getting Started CHAPTER 3 Receiving Data To receive data from the game, simply connect to the TCP Socket. The plugin uses port 30001 for clients to connect on. There are several events and different messages that are broadcast with different structures. Apart from events, data is broadcast regularly at 1 second intervals. 3.1 Putty Putty is a basic shell program that can connect to various levels of protocols and is available free of charge at http://putty.org. To view the raw data, you can open a putty window on the same machine with the game running. The host is localhost and the port is 30001. The connection type is raw. Then you can see the data as it’s broadcast in real time. You may notice the data is in JSON format which is easily decodable in multiple languages. To make it look pretty, you can copy all of it to the clipboard, then use a website like JSON Lint to make it look nice. 3.2 Programming To receive data from ETCARS, your programming language should connect using standard TCP socket. The host is localhost and the port is 30001. Once connected, you should look to your socket receive or async receive method. This will capture the data broadcast. 5 ETCARS Documentation, Release 0.14 3.3 Third Party Packages There are many other languages out there that have the ability to connect and receive ETCARS’s data. Note that none of these are officially supported by the development team of ETCARS and are maintained at the sole discretion of their authors. • JavaScript: https://www.npmjs.com/package/etcars-node-client • C#: https://github.com/shardick/etcars-dotnet-sdk 6 Chapter 3. Receiving Data CHAPTER 4 The Data 4.1 General There are several events emitted with several different data structures. Here you can look and see the different data events and the different data structures included. All data broadcast is in a JSON format with 1 exception. The string broadcast starts with an 8 character header that represents the length of the string broadcast. For most languages, this can be ignored and all data can be received then parsed by using the first { and the broadcast ends with \r. Using those points as a basis, a substring of the data can be made and then the JSON parsed into a proper JSON object. Many languages have implementations for this. Otherwise, you may look at the Third Party list of packages on the connecting page. All events have data as the root element and status available as part of the data object. 4.2 SDK Events Not all raw sdk events are broadcasted from the server. This may change in the future. The SCS SDK Events available are: • SCS Telemetry Init • SCS Telemetry Shutdown • SCS Telemetry Configuration • SCS Telemetry Frame Start • SCS Telemetry Frame End • SCS Telemetry Pause 7 ETCARS Documentation, Release 0.14 4.3 Events Some events share the same data structure, and it’s the first one documented below. Others are special events that have a different structure. The normal telemetry structure is shared by the following events: • Intialized • Telemetry • Job Started • Job Continue • Job Finished • Paused • UnPaused • No Lights • Telemetry Shut Down The special events are as follows: • Speeding • Collision • Late 4.3.1 Initialization Event This event is fired when the game is first fired up and initialization has been completed. Do not expect to capture this event as this is also when the server is being started. Unless you connect exactly when the game is started and the user clicks OK on the Additional Features screen, this event may not be received. The status contained in the data object for this event is INTIALIZED. Available since version: 0.13 4.3.2 Telemetry Event This event is fired every second to all connected clients. The status contained in the data object for this event is TELEMETRY. Available since version: 0.13 4.3.3 Job Started Event This event is fired when a job has been started. While a job may be chosen in the menu, this event does not fire until the trailer has been connected. The status contained in the data object for this event is JOB STARTED. Available since version: 0.13 8 Chapter 4. The Data ETCARS Documentation, Release 0.14 4.3.4 Job Continue Event This event is fired when a job is being resumed. When the game is exited cleanly, the current delivery information is saved to a file for the next time the delivery is resumed. The status contained in the data object for this event is JOB CONTINUE. Available since version: 0.14 4.3.5 Job Finished Event This event is fired when a job has been completed. This is fired based off of the in-game configuration event and is fired AFTER the user clicks continue on the job results screen. The status contained in the data object for this event is JOB FINISH. Available since version: 0.13 This event is fired when the game has been paused. The status contained in the data object for this event is PAUSED.