biocv_api v1.1.6

BiocvAPI

The BioCV API can be used to interact with the BioCV Cloud System and to utilize the BioCV Eartags and the BioCV Scanner. Please note that this library is under active development and thus there can be breaking changes in future. If you have any questions please contact us under info@biocv.org or create an issue.

Table of Contents

Usage
Definitions Functions

Installation

Run inside your project folder to install the library:

npm install --save biocv_cloud_api

Usage

Import the package into your destinated file. The API is using commonJS module system https://nodejs.org/docs/latest/api/modules.html

const biocv = require("biocv_cloud_api");

If you are a first time user of the library you need to create an account for your organization. You can do this by calling the function

await biocv.createAccount(email: String, password: String, username: String)
        .then(res => console.log (res))
        .catch(e => console.error(e));

To get acces too your accounts data you have to authenticate on every new session. For this reason please call

await biocv.login(email: String, password: String)
        .catch(e => console.error(e));

befor using any functions from the library.

Definitions

ThirdPartyUser - TPU

This Usertype can access and hold as many users as needed. As a user of this API you are always a TPU. You identify yourself via the thirdPartyUserID. TPU Object

{
        "mail": "bob@biocv.org",
        "name": "IVPkigtiyoU2AK1stTfsEJKSB1Q2"
}

User

A User generally represents a farmer/ farm. As a ThirdPartyUser you can create and manage Users completly. Users have limitied rights to reduce the misstakes and errors. User Object

{
        "T": 1627044216292,
        "mail": "alice@biocv.org",
        "name": "lqey4qNBFrV4wHCHOcJxAygl2qb2"
}

Eartag

A Bluetooth Eartag with embedded temperature and acceleration sensors. Eartag Object

{
        "group": "unsorted",
        "id": "ZtuzzdF_5",
        "mac": "21:27:00:00:00:01",
        "registered": "false",
        "seed": "386b62d10dd4ce346f26bcdd357e89830e459edde91994bf6aeafb7d0aa17b23",
        "t": 0
}

Node

A Node is a synonym for the AccesPoint of the eartags data. They handle their data, decodes it and processes it to the database. Moreover some characteristics of the Eartags can be changed via the nodes, such as:

• Broadcasting Intervall (Default is 1 sec)
• OS Updates Eartag Object

{
        "owner": "lqey4qNBFrV4wHCHOcJxAygl2qb2",
        "t": 1627056810478,
        "uid": "2021.0033"
}

Functions

createAccount

async function createAccount (usermail: String, password: String) : Promise<Object>

Creates a third-party Account in the BioCV Ecosystem. Use this function only if you do not already have an account. This only needs to be done once and you only need one account for handling all of your users.

login

async function login (usermail: String, password: String) : Promise<Object>

Returns a Usertoken. Must be called before using the API functions. Call this function with your BioCV Account credentials.

UserHandling

createUser

async function createUser (thirdPartyUID: String) : Promise<void>

Creates a completely new (Farmer-)User on the Server. This Useraccount can be passed to your customers to help them with the integration and usage. You will have full access to your created users. Users have limited access to the database to prevent misuse and errors.

getAllBoundUsers

async function getAllBoundUsers () : Promise<Users[]>

Returns all users registered under your Account. User Object

{
        "uid": "2021.0012",
        "t": 1627044216292
}

getAllNodesOfUser

async function getAllNodesOfUser (userID: String) : Promise<Nodes[]>

Returns all nodes of a given User. Node Object

{
        "uid": "2021.0012",
        "owner": UID,
        "t": 1627044216292
}

bindNodeToUser

async function bindNodeToUser (nodeID: String, userID: String, thirdPartyUID: String) : Promise<String>

Adds and binds a new Node to a existing User.

Eartag Handling

The following functions provide tools to handle new or existing eartags and their data.

registerEartag

Registers a new Eartag under a given user. This can also be done via the android library if needed.

async function registerEartagOnUser: async function (userID: String, eartagMAC: String, internID = null: String) : Promise<void>

setEartagGroup

Sets or changes an individual groupname of the given ear tag. This group settles under the node and can be used for a finer differentiating for e.g. the farmer. This group can be for example the name of the box, stable or whatever liked.

async function setEartagGroup: async function (mac: String, groupname: String) : Promise<void>

addNoteToEartag

Adds and writes a note to a given animal. This notes can hold any information needed to add to the animal. This could be for example:

• lameness
• sickness
• general conspicuousness
• ...

async function addNoteToEartag(userID: String, eartagMAC: String, note: String) : Promise<void>

readNotesOfEartag

Returns all written notes of a corresponding eartag.

async function readNotesOfEartag(userID: String, eartagMAC: String) : Promise<String[]>

subscribeToAllEartagsOfNode

async function subscribeToAllEartagsOfNode (nodeID: String, callback: Function, getRegularState: Boolen = false) : Observable<>

Subscribe to the events of a all eartags of a given node. This subscription will listen and fire to every event happening on all animals under a given node. You can bunch the listeners and listen to all nodes under a user or even to all nodes of all users. The Callback takes one argument which represents the event. If you call the function with getRegularState set to true, you recieve additional state updates every 30 miniutes, for every eartag of the node. The default value is set to false. The listener will nevertheless subscribe to the general eventsystem (For more information please refer to Events). State Object

{
        "battery": 404,                 // Will be added with the next update
        "T": 0,                         // Average animal temperature (last 30 mins) 
        "A": 0,                         // Average animal activity (last 30 mins) 
        "gT": 0,        
        "gA": 0,
        "t": 1627044216292,
        "mac": "00:11:22:33:44:55",
        "nodeID": "2021.0099"
}

To detach a listener simply use:

const unsub = subscribeToAllEartagsOfNode ("alice02", callback)
// ...
unsub();

If you are listening to also the state, you have to call

const unsub = subscribeToAllEartagsOfNode("alice02", callback, true, callback2)
// ...
unsub.forEach(sub => sub());

subscribeToAllEartagsOfNode

async function subscribeToAllEartagsOfUser (userID: String, callback: Function, getRegularState: Boolen = false) : Observable<>

Subscribe to the events of a all eartags of a given user. The returned values are the same as under

async function subscribeToAllEartagsOfNode (nodeID: String, callback: Function, getRegularState: Boolen = false) : Observable<>

Events

Temperature Event

Triggers when an animal has a significant higher temperature than its surrounding group. This event will be fired for any animal in the system.

{
        "event": "temperature",         // Eventtype
        "T": 32.3,                      // Average animal temperature (last 15 mins) 
        "gT": 27.4,                     // Average group temperature
        "cT": 0.978,                    // Activation value
        "A": 1.14,                      // Average aimal activity
        "t": 1627044216292,             // Timestamp (millis)
        "mac": "00:11:22:33:44:55",     // mac address
        "nodeID": "2021.0099"           // Internal used ID
}

Future Functionality

Activity Event

Triggers when an animal has a significant lower activity in the last 4 hours compared to its group. This event will be fired for any animal in the system.

Heat Event

...

Health Event

...

getCurrentTemperatureOf

Returns the current temperature of a given Eartag.

async function getCurrentTemperatureOf (earTagMAC) : Promise<Number>

getCurrentActivityOf

Returns the current activity of a given Eartag. The Activity is defined as …

async function getCurrentActivityOf (earTagMAC) : Promise<Number>

subscribeToEartag

Returns an Observable and Subscribes to the Eventsystem of an Eartag. Every time an incident (*1) happens the function will return the incident.

async function subscribeToEartag (earTagMAC) : Observable<>