Skip to content
We're currently creating a lot of content. Sign up to get notified when it's ready.

Readings

The Readings API lets you get sensor readings data from the network. There are two ways to access it:

  • Through the readings property of any Asset object, to query the readings of that asset.
  • Through live signals, to query a specific sensor stream with more control over the time range, sampling and aggregation.

Every asset exposes a readings object with the following query methods:

readings: {
latest(): Promise<AssetReadings>
forRange(start: Date, end: Date): Promise<AssetReadings>
forPeriod(): AssetReadingsCollection
}

Each reading is a Reading object:

type Reading = {
asset: string;
property: AssetProperty;
value: number;
date: Date;
unit: string;
}

The properties an asset can have readings for depend on its type. See AssetReadings and the sensors property of the Asset.

Returns the readings cached for the current simulation period, sampled with a 15 minute resolution.

forPeriod(): AssetReadingsCollection

None.

An AssetReadingsCollection: an array with one entry per 15 minute step that has readings, each containing its date and the readings for that step. It is empty when the asset has no readings.

Retrieves the latest reading of each property measured in the asset, looking back up to 15 days from the start of the current period.

latest(): Promise<AssetReadings>

None.

A promise that resolves with an object with one Reading per measured property. Properties without readings in the last 15 days are not included, and the object is empty ({}) when the asset has no sensors.

const asset = sdk.network.getAsset('Nellybay')
const readings = await asset.readings.latest()
console.log(readings)
// {
// level: { asset: 'Nellybay', property: 'level', value: 3.2, date: Date, unit: 'm' }
// }

Retrieves the readings of an asset between two dates.

forRange(start: Date, end: Date): Promise<AssetReadings>
  • start: Start date.
  • end: End date. The range between start and end can’t be greater than 15 days.

A promise that resolves with an object with an array of Reading objects per measured property. The object is empty ({}) when the asset has no sensors.

The promise is rejected if end is earlier than start, or if the range exceeds 15 days.

Get readings for 24 hours for an asset.

const asset = sdk.network.getAsset('Nellybay')
const readings = await asset.readings.forRange(new Date("2024-01-01"), new Date("2024-01-02"))
readings.level?.forEach((reading) => {
console.log(reading)
})

A LiveSignal is a descriptor of a sensor stream for a given asset and property. Get them from the network with getLiveSignals() or getLiveSignal().

type LiveSignal = {
id: string;
asset: string;
property: AssetProperty;
mappings: string[];
sampleIntervalMs: number;
at(time: Date): Promise<ReadingPropertyValue | undefined>;
inRange(timeStart: Date, timeEnd: Date): Promise<ReadingPropertyValue[]>;
samplesInRange(timeStart: Date, timeEnd: Date, intervalSeconds: number): Promise<ReadingPropertyValue[]>;
aggregateInRange(
startDate: Date,
endDate: Date,
intervalSeconds: number,
method: AggregationMethod
): Promise<ReadingPropertyValue[]>;
}
type ReadingPropertyValue = {
time: Date;
value: number | boolean;
unit?: Unit;
}
type AggregationMethod = "first" | "last" | "sum" | "count" | "avg"
  • id: Unique identifier of the signal.
  • asset: ID of the asset that produces the signal.
  • property: Property measured by the signal, such as pressure, flow or level.
  • mappings: IDs of the source signals mapped to this live signal.
  • sampleIntervalMs: Nominal sampling interval of the signal, in milliseconds.

Returns the reading nearest to (or at) the given time, or undefined if there is none.

at(time: Date): Promise<ReadingPropertyValue | undefined>

Returns all the readings between timeStart (inclusive) and timeEnd (exclusive).

inRange(timeStart: Date, timeEnd: Date): Promise<ReadingPropertyValue[]>

Returns the readings between timeStart (inclusive) and timeEnd (exclusive), sampled every intervalSeconds. Steps are aligned to timeStart, and each step takes the nearest available reading.

samplesInRange(timeStart: Date, timeEnd: Date, intervalSeconds: number): Promise<ReadingPropertyValue[]>

Returns the readings between startDate (inclusive) and endDate (exclusive), aggregated every intervalSeconds with the given method: first, last, sum, count or avg.

aggregateInRange(
startDate: Date,
endDate: Date,
intervalSeconds: number,
method: AggregationMethod
): Promise<ReadingPropertyValue[]>

Get the hourly average pressure of a junction for the last day:

const signal = sdk.network.getLiveSignal('J1', 'pressure')
if (signal) {
const end = new Date()
const start = new Date(end.getTime() - 24 * 60 * 60 * 1000)
const hourly = await signal.aggregateInRange(start, end, 3600, 'avg')
}