tirecheck-device-sdk

Tirecheck Device SDK

Usage

First, install this library as a dependency to your application:

pnpm add tirecheck-device-sdk

Then, create an instance of this SDK. You will need to provide implementation for basic bluetooth methods on your environment - this library is optimized for usage with cordova-plugin-ble-central on mobile devices, but you can provide any other implementation:

// tirecheckDeviceSdk.ts
import { createTirecheckDeviceSdk } from 'tirecheck-device-sdk'

export default createTirecheckDeviceSdk('android', {
  // See typescript definitions for more info
  startScanWithOptions: ...
  connect: ...
  write: ...
  read: ...
})


// OR, if you're using `cordova-plugin-ble-central`:
export default createTirecheckDeviceSdk('android', window.ble.withPromises)

Example library usage:

const foundBridges = {}

tirecheckDeviceSdk.bluetooth.scanDevices(device => {
  if(device.type === 'bridge') foundBridges[device.id] = device
})

await tirecheckDeviceSdk.bridge.connect(deviceId)

await tirecheckDeviceSdk.bridge.readVehicleSchema(deviceId)

Contributing

Getting started

• Install Node.js 20.0+
• Clone this repo
• Run corepack enable (sometimes sudo corepack enable is needed)
• pnpm dev

That should open Vitest's UI. Feel free to add new functionality and tests.

Publishing your changes

CI is set up in a way that new version of package is published to NPM if change in package.json's version field is detected. So, if you want to publish your changes, increment version in package.json as part of your merge request.

Test-driven development

For this project, we advice to follow TDD for every feature. That means that you first write failing test, and then add implementation so that test passes.

Focus on one small improvement at a time - one failing test, then make it pass, then another failing test, etc. Mentally this approach is much easier because you don't need to think about system as a whole

Local testing in app

To test the library in your application, without publishing them to npm, please, run following commands:

// From /Work/tirecheck-device-sdk
pnpm build

// From /Work/my-app
pnpm link ../tirecheck-device-sdk

This will temporarily ensure that package is taken from your local directory and not from package.json.

Conventions

• use deviceMeta for storing generic device info and methods for processing advertisement for all supported devices
  • this is to avoid importing full device services before we're connected to them
• use devices/* for exposed logic related to devices after they're connected. That includes methods connect and disconnect.
• For more complicated devices, such as bridge, it is useful to create bridgeCommands file, that contain commands. Command = method that accepts human-readable arguments and converts them to single low-level call of ble (i.e. it just converts human-readable data to binary data and sends them to ble).

// bridge.ts - methods from this file are exposed to library users
import bridgeCommands from './bridgeCommands'

export default {
  // You can expose command directly...
  getMeasurement: bridgeCommands.getMeasurement,

  // Or expose method that calls sequence of commands
  async getVehicleSchema() {
    const axles = await bridgeCommands.getVehicleAxles()
    for(let i = 0; i < axles.length; i++) {
      const tyres = await bridgeCommands.getVehicleTyres(i)
    }
    return { axles, tyres }
  }
}

• use services/* for logic shared between devices. Those files won't be exposed in the build.
• expose only top-level functions. So, expose bridge.writeConfiguration or bridge.writeAxleSetup instead of generic bridge.writeMessage
• in device services, use verbs read* and write* for methods that primarily read/write to/from device
• use on* for "subscription" methods - e.g. tirecheckDeviceSdk.bridge.onMeasurementReceived(callback)
• for devices that expose additional info via advertisings, do not report them while advertising data is incomplete.
• don't use this keyword.

// Bad
export default {
  foo() {},
  bar() {
    this.foo()
  }
}

// Good
export default {
  foo,
  bar() {
    foo()
  }
}

function foo() {}

Simulator

For each supported device, you must provide a simulator. It is important for testing final apps. Simulator replaces high-level calls - i.e. it works with human-readable data and doesn't need to convert data to binary

• For complex devices with commands layer, such as bridge example above, we advice to simulate only commands layer, and leave top-level as is

Submitting changes

If you wish to include a new change, process is as follows:

• You need to have a Jira ticket related to your change
• Create a new branch from latest main that includes your name and ticket number from Jira, e.g. leonid-buneev/INF-1234
• Commit and push your changes to this new branch.
• Create a Merge Request in https://tycgitlab.tyrecheck.com/leonid.buneev/tirecheck-device-sdk/-/merge_requests
• Wait for review
• After ticket is merged, new SDK version will be published to NPM automatically.
• Bump version of tirecheck-device-sdk in the package.json of your app to download latest SDK version.

Support

You can contact tirecheck if you need support - [e-mail]

Roadmap

[x] Initial structure

[x] Simulators

[x] Ability to test against real devices

[x] Full CAN bridge support

[x] CAN Bridge Firmware Update support

[x] FlexiGauge

[] TPMS Router

Devices

Each device has its own methods for communication. Generic bluetooth methods are not exposed.

Bridge

• connect
• disconnect
• getVehicle
• setVehicle
• getConfiguration
• setConfiguration
• getSensorReading
• getVehicleReadings
• getAutolearnStatuses
• resetAutolearnStatuses
• updateFirmware

Bridge OTA

• connect
• disconnect
• updateFirware

Flexi Gauge TPMS

• connect
• disconnect
• onTreadDepth
• onButtonPress
• onTpms
• getBattery
• startTpmsScan