Skip to content

Getting Started with vTAG Service#

This guide takes you from a fresh PC to a vTAG model producing outputs from a Kafka stream.

A Kafka broker is the message server that carries telemetry between applications. A producer is any application that publishes telemetry to it, and a consumer, such as ATLAS, reads it. vTAG Service is both: it reads your model's inputs from the broker and publishes the model's outputs back to it.

1. Check the prerequisites#

You need

  • A Kafka broker that vTAG Service can reach. If you don't have one yet, Getting Started with Open Streaming shows how to run one in Docker.
  • A producer publishing telemetry to that broker using the Open Streaming Architecture: for example ADS with the Bridge Service, or your own application built on the Stream API. The session must contain the parameters your model reads.
  • System Monitor, to program your model onto vTAG Service.
  • A built vTAG application: the .pgv file, plus the .cfg (logging configuration) and, if your application uses them, .pul files that go with it. You build these the same way as for vTAG Server; see Create Your First vTAG Server Model and Build the Application. Note the folders they are in: you'll need them in step 4.
  • A Motion Applied licence file (.lic) with the vTAG Server feature. vTAG Service uses the same licence feature, but you don't need vTAG Server installed.

Note

You don't need vTAG Server, ATLAS 9 or ADS installed. You also don't need to install .NET separately, because vTAG Service ships with its own runtime.

2. Install vTAG Service#

  1. Download the vTAG Service installer, MA.DataPlatforms.vTAGService.Setup.exe, from the Motion Applied Portal.
  2. Run it and follow the wizard.

The installer:

  • installs Licence Manager if it isn't already installed, or if your copy is older than the one in the installer;
  • installs vTAG Service to C:\Program Files (x86)\Motion Applied\MA.DataPlatforms.vTAGService;
  • adds vTAG Service shortcuts to the Start Menu (under Motion Applied) and the desktop;
  • creates your configuration file, Documents\Motion Applied\vTAG Service\AppConfig.json, if you don't already have one.

3. Import your licence#

Open Licence Manager from the Start Menu and import your .lic file.

vTAG Service reads the licence from %APPDATA%\McLaren Applied Technologies\Licence.lic when it starts. If that file isn't there, the service stops straight away (see Troubleshooting).

4. Point vTAG Service at your broker and files#

AppConfig.json is a text file that holds vTAG Service's settings. Open Documents\Motion Applied\vTAG Service\AppConfig.json in a text editor such as Notepad. The installer creates it with defaults; change the highlighted values to suit your setup:

AppConfig.json (values to check)
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
{
  "StreamApiConfig": {
    "BrokerUrl": "localhost:9094",
    ...
  },
  "VTagHost": {
    "DataSource": "Default",
    ...
  },
  "EssentialsConfig": {
    "PgvPaths": [
      "C:\\McLaren Applied"
    ],
    "CfgPaths": [
      "C:\\McLaren Applied"
    ],
    "PulFilePaths": [
      "C:\\McLaren Applied"
    ]
  }
}

Edit only these values; leave the rest of the file as it is

... marks settings that are left out of this example. Don't delete them from your file.

  • StreamApiConfig.BrokerUrl: the host:port your Kafka broker listens on. The default file's localhost:9094 is only a starting value: use your broker's actual address and port. For example, the Docker broker from Getting Started with Open Streaming listens on localhost:9092.
  • VTagHost.DataSource: the name of the data source your producer publishes telemetry under. vTAG Service reads its inputs from it. For the Bridge Service, it's the DataSource value in the Bridge Service's configuration file. If you're not sure, ask whoever set up the stream; many setups use Default.
  • EssentialsConfig paths: the folders that hold the .pgv, .cfg and .pul files for the model you'll program. In JSON, write each backslash twice (\\).

Save the file. vTAG Service reads it only when it starts. If it's already running, close its console window and start it again. For every setting, see the Configuration Reference.

5. Start vTAG Service#

Start vTAG Service from the Start Menu or the desktop shortcut. A console window opens and shows the service's log. Keep this window open: closing it stops the service.

When it starts successfully, you'll see lines like these. The first line shows that vTAG Service has connected to your broker.

Log (console or file)
Support Library started (broker: "localhost:9094")
vTAG not running at startup (state ...) — deferring discovery until it reaches Running

The second line is expected on a new installation: no model has been programmed onto vTAG Service's built-in virtual vTAG unit yet.

6. Program your model with System Monitor#

With vTAG Service running:

  1. Open System Monitor.
  2. Create a New Project (File > New > Project).
  3. Select the BIOS Program Version. If vtag.build didn't specify a BIOS version, the default is 4; select a 1000 BIOS version.
  4. Select all of the App IDs in the selected base and load your generated PGVs.
  5. Click Finish.
  6. Connect to the IP address in VTagClient.BindIpAddress. The default is 127.0.0.1, so System Monitor must run on the same PC.
  7. Reprogram the unit (F3).

These are the same steps as for vTAG Server, except that there is no Reset vECU step: vTAG Service has no reset option of its own.

When programming finishes, vTAG Service reads the model's parameters and subscribes to the broker:

Log (console or file)
vTAG reached Running from ... — (re)discovering
vTAG reached Running — resetting state and rediscovering parameters
Parameter discovery complete: 1 slot(s), 4 inputs, 12 outputs
Subscribing vTAG model to Support Library (frequency: 1000 Hz, batchSize: 100)
Successfully subscribed to Support Library. SubscriptionId: "..."

The numbers depend on your model: slot(s) is the number of applications programmed onto the unit, and the frequency is the rate your model runs at (its base step). Once you see Successfully subscribed, vTAG Service is ready for data.

7. Stream a session and check the outputs#

Start streaming a session that contains your model's input parameters to the broker, on the data source you configured. vTAG Service runs the model as the data arrives. It writes the outputs to an associated session: a new session on the same broker, linked to your input session, with the session type vTAG.

To see the outputs in ATLAS:

  1. Add a Stream Recorder whose Stream Server Configuration points at the same broker. Its Domain and Stream Creation Strategy must match StreamApiConfig; if you haven't changed them, leave the Domain empty and choose Topic Based.
  2. Start the recorder.

You'll know it's working when the vTAG output session appears alongside your input session and your model's output parameters show values. To save the outputs without ATLAS, use the Standalone Stream Recorder.

If something doesn't work#