Skip to content

Quickstart

SensorChaos has three levels of integration. Start at the one that fits your situation — you can always go deeper later.

ModeRequiresWhat you get
1 — Zero integrationCLI + Android emulatorGPS injection on emulators in 2 minutes, no app changes
2 — Light integrationCLI + agent SDK in your debug appReal devices, full sensor injection (IMU, barometer, magnetometer), 14 scenarios
3 — Full powerMode 2 + CI pipelineAssertion gates, JSON reports, automated resilience regression detection

Mode 1 — Zero integration

Section titled “Mode 1 — Zero integration”

No app changes needed. Connect an Android emulator, install the CLI, and run a scenario. Good for a first look or for testing any third-party app.

  1. Install the CLI

    Via Homebrew (macOS / Linux):

    Terminal window
    brew tap sensorchaos/tap
    brew install sensorchaos

    Or via the install script:

    Terminal window
    curl -fsSL https://sensorchaos.com/install.sh | sh

  2. Try the demo

    Terminal window
    sensorchaos demo

    Runs a spoofing scenario against a built-in sample app — no device, no key, no app changes. Good first sanity check that everything installed correctly.

  3. Activate your license key

    Terminal window
    sensorchaos auth <your-key>

    Start a free 14-day trial at sensorchaos.com/trial — no credit card required.

  4. Start an Android emulator and confirm ADB sees it

    Terminal window
    adb devices
    # emulator-5554   device

  5. Run a scenario

    Terminal window
    sensorchaos run gnss/gulf-spoofing-2026

    The CLI injects GPS coordinates directly via ADB (geo fix). No agent, no app code.

You’re up and running when the scenario completes and you see a resilience score in the terminal.

Mode 2 — Light integration

Section titled “Mode 2 — Light integration”

Add the agent SDK to your debug app. This unlocks real devices, full sensor injection (GPS + IMU + barometer + magnetometer), the two-way agent protocol, and all 14 scenarios including multi-sensor ones.

  1. Complete Mode 1 steps 1–2 (CLI installed, key activated)

  2. Add the agent to your debug app

    Add the dependency to your app’s build.gradle.kts:

    dependencies {
        debugImplementation("dev.sensorchaos:agent:0.1.0")
    }

    Wrap your Application context:

    class MyApp : Application() {
        override fun attachBaseContext(base: Context) {
            super.attachBaseContext(SensorChaos.wrap(base))
        }
    }

    That’s it — no other changes needed. The agent is a complete no-op in release builds.

  3. Build and install your debug app onto the device

  4. Run a scenario with --agent

    Terminal window
    sensorchaos run gnss/gulf-spoofing-2026 --agent

    The CLI auto-forwards port 19847 over ADB. Works on both emulators and real devices.

    Terminal window
    # Multiple devices? Specify one:
    sensorchaos run gnss/gulf-spoofing-2026 --agent --device emulator-5554

You’re up and running when you see ✓ Connected to agent on port 19847 in the terminal output.

Mode 3 — Full power (CI)

Section titled “Mode 3 — Full power (CI)”

Add assertion flags and a JSON report to your CI pipeline. Fail builds automatically when resilience drops below your threshold.

  1. Complete Mode 2

  2. Add an assertion threshold

    The --assert-max-position-error-km flag causes the CLI to exit non-zero if the maximum position error exceeds the threshold — failing the CI job:

    Terminal window
    sensorchaos run gnss/gulf-spoofing-2026 --agent \
      --assert-max-position-error-km 10

  3. Save a JSON report

    Terminal window
    sensorchaos run gnss/gulf-spoofing-2026 --agent \
      --assert-max-position-error-km 10 \
      --report report.json

    The JSON report includes the full resilience score breakdown, timeline events, and per-phase metrics — suitable for test dashboards and artifact storage.

  4. Wire it into CI

    - name: Run GPS resilience test
      run: |
        sensorchaos run gnss/gulf-spoofing-2026 --agent \
          --assert-max-position-error-km 10 \
          --report resilience-report.json
    

    - name: Upload resilience report
      uses: actions/upload-artifact@v4
      with:
        name: resilience-report
        path: resilience-report.json

    See CI/CD Integration for the full GitHub Actions and GitLab CI templates.

  5. Run all scenarios as a suite

    Terminal window
    sensorchaos suite --scenarios gnss/ --agent \
      --assert-max-position-error-km 10 \
      --report suite-report.json

You’re up and running when your CI pipeline fails on a resilience regression and uploads a JSON report as an artifact.

Next steps

Section titled “Next steps”