Unofficial NodeJS package for the Canary Axiom Web API
npm install canarylabs-web-api
require("dotenv").config({ path: "./process.env" });
const canary = require("canarylabs-web-api");
// Basic running example
const credentials = {
username: process.env.MY_USERNAME || "default_username",
password: process.env.MY_PASSWORD || "default_password",
baseURL:
process.env.MY_BASE_URL ||
"https://yourdomain.canarylabs.online:55236/api/v2",
};
let userTokenBody = {
application: "Web API",
timezone: "Eastern Standard Time",
};
// Example usage:
(async () => {
try {
let result = await canary.getUserToken(credentials, userTokenBody);
console.log("User Token : " + result.userToken);
} catch (error) {
console.error("Error:", error);
}
})();
Automatically store all tag values in an object where the key:value = "Full.Tag_name123" : latest value for simple recall, I have found this very useful.
Usage:
let tagValues = await canary.storeLatestValues(credentials);
Result:
// example
var pressureTag1 = tagValues["Company.Site.Pressure.pressure1"]
console.log(pressureTag1+" bar")
// result 1.57 bar
This allows you to use the Axiom tag reference to directly call a live value without having to process it manually fro the API response.
The Canary API returns null
on any processed data request i.e an average or delta request, if that tag has been sitting at 0 for the whole request period. This is also an issue with the API usage on the Axiom dashboard system, where averages and deltas etc return an error instead of 0 in value boxes. The main issue here is that will break subsquent calculations (as it does with the historian calcs), this means adding in your own error handling, so I have added this into the API with a simple helper function that will run on the returned data and sanitize null
to 0
:
function processTags(data, tags) {
console.log(data.data);
tags.forEach(tag => {
if (data.data[tag]) {
data.data[tag].forEach(item => {
console.log("item",item);
if (item.v === null) {
item.v = 0;
}
});
}
});
return data;
}
If your flow sensor does not have a pulsed output totaliser you can use this function to return a totalizer figure for a given period. the body key of aggregateInterval
will determine the accuracy of the total, and should be used carefully, an interval of 1 second will be very accruate, but over a period of the more than a few hours will return too many values. Whereas an interval of 1 hour will return fewer values, but will be less accurate as a total.
// Dates should be mm-dd-yyyy, seconds, minutes, hours, days, weeks are also acceptable semantic start and end times.
let totalizer = await canary.softTotalizer(credentials, {
"userToken": "{{UserToken}}",
"tags": ["Company.Site.Flow.FT1731_PV"],
"startTime": "now - 2 hour",
"endTime": "now",
"maxSize": 10000000,
"aggregateName": "TimeAverage2",
"aggregateInterval": "30 seconds"
});
console.log("response; ",totalizer);
};
For calculating the run hours of equipment based on a key production parameter, such as flowrate, pressure, power, frequency etc.
Identical to the soft totalizer with an additional paratmeter of threshold
which is there to account for noise i.e. a flow meter might have a threshold of "1" to avoid reading of <1 from triggering the run count:
let threshold = 1 // where the threshold is the lowest value that the parameter might read when not running
let runHours = await canary.softRunHours(credentials, {
"userToken": "{{UserToken}}",
"tags": ["company.site.Flow.FT2900_PV"],
"startTime": "12-01-2023",
"endTime": "now",
"maxSize": 10000000,
"aggregateName": "TimeAverage2",
"aggregateInterval": "10 seconds"
}, threshold);
console.log("response; ", runHours);
https://helpcenter.canarylabs.com/t/y4hvlzq/web-read-api-postman-example-version-23