knowgo-vehicle-simulator

An interactive multi-platform Connected Car simulator for generating
and streaming realistic vehicle telemetry.

Overview

knowgo-vehicle-simulator has been developed to aid in the
development and validation of data-driven Connected Car services and
models that require easy access to realistic synthetic driving data,
both for static and streaming applications. It was originally designed
for generating event records for the KnowGo Car platform, but has
been generalized so that it may be useful both to Connected Car service
developers and researchers.

The vehicle simulator generates a single unique vehicle, which can
be controlled either directly through the UI or through an optional
REST API. This may be further interfaced with OEM-specific external
data sources and models in order to permit the simulation state to act
as an automotive digital twin. For fleet simulation workloads, multiple
instances of the simulator may be run in parallel, with each generated
vehicle being manually joined to a specified fleet.

Live Demo

A live demonstration of the Simulator is available here.

Installation

Installation from a binary release is recommended. Regular releases are
made to various app stores, please refer to the one appropriate for
your platform:

Releases can also be obtained directly from GitHub.

Deployment

For deployment of a self-contained web-based instance of the simulator,
a number of deployment options have been provided:

Docker

Multi-arch images are provided under knowgo/knowgo-vehicle-simulator.
The image can be run directly as:

$ docker run -p 8086:8086 knowgo/knowgo-vehicle-simulator

Kubernetes

To create a Kubernetes Deployment including a single instance of the
simulator:

$ kubectl apply -f https://raw.githubusercontent.com/knowgoio/knowgo-vehicle-simulator/simulator-deployment.yaml

An optional Service exposing the simulator port on the cluster can
also be applied:

$ kubectl apply -f https://raw.githubusercontent.com/knowgoio/knowgo-vehicle-simulator/simulator-service.yaml

Simulator UI

Documentation

For additional documentation and tutorials, please refer to the documentation.

Postman Collection for Simulator REST API

A Postman Collection and pre-configured environment for interacting
with the Simulator REST API in a local simulation environment is
available here.

Architecture

The Simulator itself consists of several different components:

The Vehicle Simulation model
An Event loop for generating vehicle events, run as either
an Isolate or Web Worker depending upon the target platform.
An optional HTTP Server isolate for exposing a REST API with basic
vehicle controls - starting/stopping the vehicle, updating the
vehicle state, handling vehicle notifications, and querying vehicle
events.

As the simulation state can not be shared directly across the isolates,
the simulation model in the main isolate acts as the source of truth
across the system:

Updates from the Event loop are applied to the simulation model
periodically, in line with the event generation frequency: once
per second by default.
The HTTP Server isolate maintains its own cached copy of the
simulation state, which is updated with changes from the Event
isolate, UI interaction, and the REST API. Changes received through
the REST API are cached in the HTTP Server isolate and proxied back
to the simulation model directly.
The UI in the main isolate is redrawn based on changes to the
simulation model, triggered by UI interaction and updates from the
Event loop or HTTP Server isolate.

An overview of the overall interactivity patterns for the different
target platforms is provided in the table below:

Flutter Web	Other Target Platforms

Implementation Status

Event Publication

By default, generated events are only logged in the console. Events can
be published to a custom notification endpoint, a KnowGo API backend,
as well as MQTT and Kafka brokers (as well as any combination thereof).
The specific configuration for each is outlined below.

Configuration

Configuration of the simulator can be tuned through a config.yaml
file, which will be parsed and updated by configuration changes within
the UI. The format of the file is:

sessionLogging: true
eventLogging: true

# Allow unauthenticated requests to REST API
allowUnauthenticated: true

# Optional endpoint to post generated events to
notificationUrl: http://myserver.com/endpoint

# Optional KnowGo Backend Configuration
knowgo:
  server: <knowgo-API-server>
  apiKey: <knowgo-API-Key>

# Optional Kafka Broker Configuration
kafka:
  broker: <kafka-broker-address>
  topic: <kafka-topic>

# Optional MQTT Broker Configuration
mqtt:
  broker: <MQTT-broker-address>
  topic: <MQTT-topic>

A number of environment variables can also be set:

Environment Variable	Description	Default value
KNOWGO_VEHICLE_SIMULATOR_CONFIG	Path to config file	`<appDocDir>/knowgo_vehicle_simulator/config.yaml`
KNOWGO_VEHICLE_SIMULATOR_LOGS	Path to log directory	`<appDocDir>/knowgo_vehicle_simulator/logs`
KNOWGO_VEHICLE_SIMULATOR_IP	IP address to bind for REST API	0.0.0.0
KNOWGO_VEHICLE_SIMULATOR_PORT	HTTP port to bind for REST API	8086
KNOWGO_SIGNING_KEY	Signing and validation secret for API keys	secret-key

Features and bugs

Please file feature requests and bugs at the issue tracker.

License

Licensed under the terms of the MIT license, the full version of which
can be found in the LICENSE file included in the distribution.

knowgoio/knowgo-vehicle-simulator