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. Available since version: 0.13
4.3.6 Game UnPaused Event
This event is fired when the game is unpaused. The status contained in the data object for this event is UNPAUSED. Available since version: 0.13
4.3.7 No Lights Event
This event is fired when drivers should have their lights on but do not. This uses game time to calculate 7AM to 7PM. The status contained in the data object for this event is NO LIGHTS. Available since version: 0.13
4.3.8 Telemetry Shut Down Event
This event is fired when the game is closing. This event may not be captured due to the way the SDK works. The status contained in the data object for this event is TELEMETRY SHUT DOWN. Available since version: 0.13
4.3.9 Collision Event
This event is fired when the minimal detectable damage has been detected, this results in a possible collision. The player may have collided with a pole, AI, another driver, etc. . . The status contained in the data object for this event is COLLISION. Available since version: 0.13
4.3.10 Late Delivery Event
This event is fired when the delivery is now past the time due for the game. The status contained in the data object for this event is LATE. Available since version: 0.13
4.3.11 Speeding Event
This event is fired when the truck speed exceeds the speed limit by 7 meters / second(~15mph/~25kmh) The status contained in the data object for this event is SPEEDING. Available since version: 0.13
4.3. Events 9 ETCARS Documentation, Release 0.14
4.4 Structures
4.4.1 Normal Telemetry Structure
For more detailed information, consult SCS Software’s SDK and the examples it contains. Especially for Velocities, Accelerations, and Offsets. The normal telemetry structure is as follows:
########{ data:
˓→Truck Simulator" gameVersionStr:
˓→may be provided regardless if fatigue simulation is enabled or disabled. gameDateTime:
˓→Jan 1, 2001. gameDayTime:
˓→and time. Example: Mon 14:53 gameDateTimeStr:
˓→date and time. Example: 2001-01-01 14:53 osEnvironment:
˓→value(s): "Linux", "Windows" architecture:
˓→"x86","x64" localScale:
˓→compensate for the scale of the map. 1s real time = localScale time. Example:
˓→localScale is 19, in 1 second real time, 19 seconds passed in-game. NOTE: 1:1 maps
˓→will not provide this channel. substances:
˓→configured substances. This is used for the wheel substance to determine the
˓→substance each wheel is touching. }, "truck": { cruiseControlSpeed:
˓→disabled. gear:
˓→gears, 0 - neutral, <0 - reverse gears. (continues on next page)
10 Chapter 4. The Data ETCARS Documentation, Release 0.14
(continued from previous page) gearDisplayed:
˓→in the dashboard. retarderBrakeLevel:
˓→max> where 0 is disabled retarder and max is the maximal value in the truck
˓→configuration. wipersOn:
˓→ Encoded using utf8mb4. makeID:
˓→identifier characters and dots. model:
˓→language. Encoded using utf8mb4. modelID:
˓→identifier characters and dots. shifterType:
˓→configured for. odometer:
˓→kilometers. hasTruck:
˓→selected truck in game. If false, the truck information is no longer valid and the
˓→user has no truck. engineEnabled:
˓→configured truck. electricsEnabled:
˓→enabled on the configured truck. motorBrake:
˓→engaged. parkingBrake:
˓→engaged. speed:
˓→of the brakes in degrees celsius. This is for the entire truck and not at the wheel
˓→level. fuelRange:
˓→amount of fuel in km. oilPressure:
˓→inch). oilTemperature:
˓→of the oil in degrees celsius. waterTemperature:
˓→of the water in degrees celsius. batteryVoltage:
˓→the battery. inputSteering:
˓→-1.0. inputThrottle:
˓→accounts for interpolation speeds and simulated counterforces for inputs. <-1,1>. effectiveThrottle:
˓→Accounts for the press attack curve for inputs and cruise control input. <0,1>. effectiveBrake:
˓→for the press attack curve for inputs, excludes retarder, parking and motor brakes.
˓→<0,1>. effectiveClutch:
˓→Accounts for automatic shifting/interpolation of player input. <0,1>. (continues on next page)
4.4. Structures 11 ETCARS Documentation, Release 0.14
(continued from previous page) hShifterSlot:
˓→currently in, 0 = no slot selected. brakeAirPressure:
˓→psi(pounds per square inch). adBlue:
˓→always be 0 in American Truck Simulator(ats). daasboardBacklight:
˓→factor. <0,1>. forwardGearCount:
˓→undamaged truck. reverseGearCount:
˓→undamaged truck. retarderStepCount:
˓→Zero if retarder is not mounted to truck. trailerConnected:
˓→connected to the truck. worldPlacement:
˓→75 = east, 0.5 = south, 0.25 = west pitch:
12 Chapter 4. The Data ETCARS Documentation, Release 0.14
(continued from previous page) roll:
˓→forward gear ratio. reverseRatios:
˓→reverse gear ratio. wheelCount:
˓→this array should match the wheel count. Each wheel object will have the following
˓→properties: [ { suspensionDeflection:
˓→wheel from its axis in meters. onGround:
˓→touching. This is value is in the substances array. Default/Air: static. angularVelocty:
˓→rotations per second. Positive = forward. lift:
˓→ 1 = fully lifted, zero for non-liftable axles. liftOffset:
˓→from its normal position in meters as result of lifting. Might have non-linear
˓→relation to lift ratio. Set to zero for non-liftable axles. position:
˓→simulated. (continues on next page)
4.4. Structures 13 ETCARS Documentation, Release 0.14
(continued from previous page) radius:
˓→rotations. <-0.25,0.25>. Counterclockwise direction when looking from top. 0.25 =
˓→left, -0.25 = right. Set to zero for non-steered wheels. rotation:
˓→ <0,1> range in which value increase corresponds to forward movement. powered:
˓→placement. { x:
˓→warning light is on. airPressure:
˓→light is on. airPressureEmergency:
˓→emergency warning light is on. oilPressure:
˓→light is on. waterTemperature:
˓→warning light is on. fuelLow:
˓→NOTE: Always false in American Truck Simulator(ats). }, damages:
˓→1 is 100% damage and 0 is 0% damage. { engine:
˓→ 2 = full brightness. beacon:
˓→off. parking:
˓→off. brake:
14 Chapter 4. The Data ETCARS Documentation, Release 0.14
(continued from previous page) reverse:
˓→off. leftBlinkerEnabled:
˓→lights are activated or not. rightBlinkerEnabled:
˓→lights are activated or not. leftBlinkerOn:
˓→are on or off. rightBlinkerOn:
˓→lights are on or off. roofAux:
˓→2 = full brightness. }, fuel: { capacity:
˓→which the warning light will turn on. <0,1>. To calculate the litres, simply take ˓→capacity and multiply it by this value. Example: capacity of 100 litres * ˓→warningLevel of 0.15 = 15 Litres. At 15 litres, the fuel warning light will turn on
˓→in this example. consumptionAverage:
˓→litres/km. currentLitres:
˓→waypoint is hit OR distance remaining until the company of the delivery is reached.
˓→Represented in meters. NOTE: When electronics are disabled or when route advisor is
˓→completely disabled, this value will ALWAYS be 0. time:
˓→destination point is reached. lowestDistance:
˓→= no speed limit. }, job:
˓→identifier characters and dots. cargo:
˓→language. Encoded in utf8mb4. mass:
˓→American Truck Simulator(ats). EUR for Euro Truck Simulator 2(ets2). This value
˓→will not update due to damage, bonuses, or on the finish screen. destinationCityID:
˓→identifier characters and dots. destinationCity:
˓→game language. Encoded in utf8mb4. destinationCompanyID:
˓→Limited to C-identifier characters and dots. destinationCompany:
˓→in-game language. Encoded in utf8mb4. sourceCityID:
˓→identifier characters and dots. (continues on next page)
4.4. Structures 15 ETCARS Documentation, Release 0.14
(continued from previous page) sourceCity:
˓→ Encoded in utf8mb4. sourceCompanyID:
˓→identifier characters and dots. sourceCompany:
˓→language. Encoded in utf8mb4. deliveryTime:
˓→late in-game. Represented in number of minutes since Jan 1, 2001. isLate:
˓→delivery is late. }, trailer:
˓→information. The number of objects in this array should match the wheelCount. The
˓→object layout is shown below: [ { suspensionDeflection:
˓→wheel from its axis in meters. onGround:
˓→touching. This is value is in the substances array. Default/Air: static. angularVelocty:
˓→rotations per second. Positive = forward. lift:
˓→ 1 = fully lifted, zero for non-liftable axles. liftOffset:
˓→from its normal position in meters as result of lifting. Might have non-linear
˓→relation to lift ratio. Set to zero for non-liftable axles. position:
16 Chapter 4. The Data ETCARS Documentation, Release 0.14
(continued from previous page) { x:
˓→simulated. radius:
˓→rotations. <-0.25,0.25>. Counterclockwise direction when looking from top. 0.25 =
˓→left, -0.25 = right. Set to zero for non-steered wheels. rotation:
˓→ <0,1> range in which value increase corresponds to forward movement. powered:
˓→dots. cargoAccessoryId:
˓→trailer. Limited to C-identifier characters and dots. hookPosition:
˓→vehicle space { x:
˓→using the Steamworks SDK. { steamID:
˓→does NOT include mods or mods downloaded from the steam workshop. The layout of the
˓→object is shown below: [ { appid:
˓→web api. name:
˓→available for purchase. installed:
˓→DLC installed. } ] }
} }, jobData:
˓→would be for a virtual trucking company or reporting service. Cirtical parts of
˓→this data are saved to encrypted files for job resume, however it is possible(continues on for next page)
˓→users to edit the data if it is decrypted properly. USE AT YOUR OWN RISK. All
˓→damages are floats with a range of <0,1> where 1 is 100% damage and 0 is 0% damage. 4.4. Structures 17 ETCARS Documentation, Release 0.14
(continued from previous page) { status:
˓→Cancellation detection is difficult and may not be functioning properly. wasSpeeding:
˓→delivery. Speeding qualifies as 7 meters per second ABOVE the reported speed limit. jobStartedEventFired:
˓→been fired. isMultiplayer:
˓→(False=delivery finished or cancelled). wasFinished:
˓→not be accurate for certain types of deliveries. wasTrailerDisconnected:
˓→disconnected at time of "finish". Used in cancellation detection. cargoID:
˓→identifier characters and dots. cargo:
˓→language. Encoded in utf8mb4. trailerMass:
˓→American Truck Simulator(ats). EUR for Euro Truck Simulator 2(ets2). This value
˓→will not update due to damage, bonuses, or on the finish screen. destinationCityID:
˓→identifier characters and dots. destinationCity:
˓→language. Encoded in utf8mb4. destinationCompanyID:
˓→C-identifier characters and dots. destinationCompany:
˓→game language. Encoded in utf8mb4. sourceCityID:
˓→characters and dots. sourceCity:
˓→Encoded in utf8mb4. sourceCompanyID:
˓→identifier characters and dots. sourceCompany:
˓→language. Encoded in utf8mb4. deliveryTime:
˓→late in-game. Represented in number of minutes since Jan 1, 2001. isLate:
˓→delivery is late. truckMake:
˓→language. Encoded using utf8mb4. truckMakeID:
˓→identifier characters and dots. truckModel:
˓→language. Encoded using utf8mb4. truckModelID:
˓→identifier characters and dots. gameID:
˓→Simulator" gameVersion:
18 Chapter 4. The Data ETCARS Documentation, Release 0.14
(continued from previous page) topSpeed:
˓→second. speedingCount:
˓→is picked up to the delivery finished event in km. fuelBurned:
˓→litres. fuelPurchased:
˓→delivery in litres. startOdometer:
˓→kilometers. endOdometer:
˓→delivery is considered late. timeStarted:
˓→Minutes since Jan 1 2001. timeDue:
˓→Jan 1 2001. timeDelivered:
˓→Minutes since Jan 1 2001. collisionCount:
˓→ocurred on the job. finishTrailerDamage:
˓→finished. deliveryY:
˓→finished. deliveryZ:
˓→finished. pickupX:
˓→up. pickupY:
˓→up. pickupZ:
˓→up. trailerDeliveryX:
˓→was finished. trailerDeliveryY:
˓→was finished. trailerDeliveryZ:
˓→was finished. trailerPickupX:
˓→picked up. trailerPickupY:
˓→picked up. trailerPickupZ:
˓→picked up. startEngineDamage:
4.4. Structures 19 ETCARS Documentation, Release 0.14
(continued from previous page) finishWheelDamage:
˓→the delivery. fuel:
˓→picked up. realTimeEnded:
˓→finished. realTimeTaken:
4.4.2 Speeding Structure
The speeding structure is as follows:
########{ data:
˓→speed limit x:
20 Chapter 4. The Data ETCARS Documentation, Release 0.14
4.4.3 Collision Structure
The collision structure is as follows:
########{ data:
4.4.4 Late Structure
The late structure is as follows:
########{ data:
˓→delivery will be consiedered late. Represented in number of minutes since Jan1,
˓→2001. currentGameTime:
˓→minutes elapsed in-game since Jan1, 2001. x:
4.4. Structures 21 ETCARS Documentation, Release 0.14
(continued from previous page) z:
˓→suggested value in the game's default currency. } } }\r
22 Chapter 4. The Data