API docs by Redocly

Normal Framework API Documentation (3.5.0-6)

Download OpenAPI specification:Download

ApplicationService

GetApplications

An application wraps a number of hooks and other resources which run within the same runtime environment.

Each application shares a number of pieces: Runtime: there is a single runtime for an application Hook: an application can have multiple hooks with different definitions and run modes. Files: the application directory can have files with code or arbitary data. Git URL: applications may be backed by a git repository Options: an application may define options to allow the user to configure settings without needing to edit the application code.

query Parameters
name
string
pageSize
string
pageCount
string

Responses

Response samples

Content type
application/json
{
  • "applications": [
    ],
  • "totalCount": "string"
}

CreateApplication

Create a new application, which is a container for hooks.

If GitUrl is set, this will clone the git repository and call UpdateDependencies on the result.

Request Body schema: application/json
object (ApplicationAuth)
compatibilityDate
string
description
string
gitUrl
string
id
string
object (Layer)
minNfVersion
string
name
string

human name for the application

Array of objects (ConfigurationOption)
runtime
integer <enum>

Responses

Request samples

Content type
application/json
{
  • "auth": {
    },
  • "compatibilityDate": "string",
  • "description": "string",
  • "gitUrl": "string",
  • "id": "string",
  • "layer": {
    },
  • "minNfVersion": "string",
  • "name": "string",
  • "options": [
    ],
  • "runtime": 0
}

Response samples

Content type
application/json
{
  • "id": "string"
}

DeleteFile

Delete a file within an application

path Parameters
applicationId
required
string
query Parameters
path
string

Responses

Response samples

Content type
application/json
{ }

ReadFile

Read a file within an application container.

path Parameters
applicationId
required
string
query Parameters
path
string
offset
string
count
string

Responses

Response samples

Content type
application/json
{
  • "data": "string",
  • "totalCount": "string"
}

WriteFile

Write a complete file within an application.

path Parameters
applicationId
required
string
query Parameters
path
string
Request Body schema: application/json
Schema not provided

Responses

Response samples

Content type
application/json
{ }

DeleteApplication

Delete an application. This removes all source files and logs from the application.

path Parameters
applicationId
required
string

Responses

Response samples

Content type
application/json
{ }

InstallDependencies

InstallDependencies invokes a runtime-specific package manager to install any third-party dependencies into the runtime environment.

For the JavaScript runtime, it invokes npm install and can be used after updating the package.json file to download new upstream dependencies.

Since the installation is performed within the Normal container, it must have access to the NPM repositories (or other repositories) for this to work.

path Parameters
applicationId
required
string

Responses

Response samples

Content type
application/json
{ }

UpdateHook

Update a hook with new settings.

A hooks settings include the points it is bound to, group settings, and run mode. Changes will not take effect until RestartApplication is called; or the application restarts for some other reason.

path Parameters
applicationId
required
string
Request Body schema: application/json
object

if not blank, running the hook will create a command context with the following expiration duration. Each time the hook is run, the context will be extended by this amount.

entryPoint
string

the name of the file containing the hook definition

object (RuntimeError)
id
string
object

timeout for calling StartHook. if the timeout expires before the hook run finishes, the runtime will be killed and restarted.

object

the results of the last time the hook was run.

mode
integer <enum>

run mode

name
string

name for what this does

Array of objects (Label)
object

bindings to input points

requiredClasses
Array of strings
Array of objects (Label)

maybe we can extract these from the source in some cases

object (HookRuntimeConfiguration)
object

when to run the program. If set to nil, the hook will not run on a schedule.

status
integer <enum>

Responses

Request samples

Content type
application/json
{
  • "commandExpiration": {
    },
  • "entryPoint": "string",
  • "error": {
    },
  • "id": "string",
  • "invokeTimeout": {
    },
  • "lastRun": {
    },
  • "mode": 0,
  • "name": "string",
  • "optionalLabels": [
    ],
  • "points": {
    },
  • "requiredClasses": [
    ],
  • "requiredLabels": [
    ],
  • "runtimeConfig": {
    },
  • "schedule": {
    },
  • "status": 0
}

Response samples

Content type
application/json
{ }

DeleteHook

Delete a hook definition. This does not remove the underlying code, just the hook definition.

path Parameters
applicationId
required
string
hookId
required
string

Responses

Response samples

Content type
application/json
{ }

GetHook

Get hook by ID

path Parameters
applicationId
required
string
hookId
required
string

Responses

Response samples

Content type
application/json
{
  • "hook": {
    }
}

StartHook

Start running a new copy of a hook with a new PID. Starting the program will fail if an existing program wite same unique_id is already running.

path Parameters
applicationId
required
string
hookId
required
string
query Parameters
groups
Array of strings

if present, only run these groups. If empty, runs all groups.

Request Body schema: application/json
key
string
value
string

Responses

Request samples

Content type
application/json
{
  • "key": "string",
  • "value": "string"
}

Response samples

Content type
application/json
{
  • "error": {
    },
  • "groups": [
    ],
  • "pid": "string"
}

GetHookData

path Parameters
applicationId
required
string
hookId
required
string
Request Body schema: application/json
applicationId
string
hookId
string

Responses

Request samples

Content type
application/json
{
  • "applicationId": "string",
  • "hookId": "string"
}

Response samples

Content type
application/json
{
  • "globalVariables": [
    ],
  • "groupVariables": {
    },
  • "groups": [
    ]
}

EvaluateHookPoints

path Parameters
applicationId
required
string
hookId
required
string
Request Body schema: application/json
Array of objects (Annotation)

annotations to be added to the point query.

Array of objects (Variable)

program variables which are created once for the hook

groupFunction
string

alternatively, a JavaScript function which performs the grouping. the function must have the following prototype: function groupFn(attrs : Map<string, string>): string each distinct value the function returns will form a group

Array of objects (Variable)

program variables which are created for each group

object

list of attribute names making up the group key

labelAttribute
string

name of the attribute containing point labels. points withough this attribute will be dropped

layer
string

layer to execute the query against

object

query for input points

Responses

Request samples

Content type
application/json
{
  • "annotations": [
    ],
  • "globalVariables": [
    ],
  • "groupFunction": "string",
  • "groupVariables": [
    ],
  • "groups": {
    },
  • "labelAttribute": "string",
  • "layer": "string",
  • "query": {
    }
}

Response samples

Content type
application/json
{
  • "groups": [
    ],
  • "points": [
    ]
}

GetHookGlobalVariables

path Parameters
applicationId
required
string
hookId
required
string
Request Body schema: application/json
applicationId
string
hookId
string
labels
Array of strings
pageOffset
string
pageSize
string

Responses

Request samples

Content type
application/json
{
  • "applicationId": "string",
  • "hookId": "string",
  • "labels": [
    ],
  • "pageOffset": "string",
  • "pageSize": "string"
}

Response samples

Content type
application/json
{
  • "totalCount": "string",
  • "variables": [
    ]
}

GetHookLogs

path Parameters
applicationId
required
string
hookId
required
string
query Parameters
version
string

Responses

Response samples

Content type
application/json
{
  • "level": 0,
  • "message": "string",
  • "ts": "2019-08-24T14:15:22Z",
  • "version": "string"
}

GetHookPoints

path Parameters
applicationId
required
string
hookId
required
string
Request Body schema: application/json
applicationId
string
group
string
hookId
string
pageOffset
string
pageSize
string

Responses

Request samples

Content type
application/json
{
  • "applicationId": "string",
  • "group": "string",
  • "hookId": "string",
  • "pageOffset": "string",
  • "pageSize": "string"
}

Response samples

Content type
application/json
{
  • "points": [
    ],
  • "totalCount": "string",
  • "values": {
    }
}

ResetVariables

path Parameters
applicationId
required
string
hookId
required
string
Request Body schema: application/json
applicationId
string
globalVariables
Array of strings
groupVariables
Array of strings
hookId
string

Responses

Request samples

Content type
application/json
{
  • "applicationId": "string",
  • "globalVariables": [
    ],
  • "groupVariables": [
    ],
  • "hookId": "string"
}

Response samples

Content type
application/json
{ }

GetHookRuns

Query the log of hook invocations.

path Parameters
applicationId
required
string

these are filters for finding hook runs

hookId
required
string
Request Body schema: application/json
applicationId
string

these are filters for finding hook runs

endTime
string <date-time>
hookId
string
pageOffset
string
pageSize
string
startTime
string <date-time>
state
integer <enum>

Responses

Request samples

Content type
application/json
{
  • "applicationId": "string",
  • "endTime": "2019-08-24T14:15:22Z",
  • "hookId": "string",
  • "pageOffset": "string",
  • "pageSize": "string",
  • "startTime": "2019-08-24T14:15:22Z",
  • "state": 0
}

Response samples

Content type
application/json
{
  • "runs": [
    ],
  • "totalCount": "string"
}

GetRuntimesStatus

path Parameters
applicationId
required
string
hookId
required
string
Request Body schema: application/json
applicationId
string
hookId
string

Responses

Request samples

Content type
application/json
{
  • "applicationId": "string",
  • "hookId": "string"
}

Response samples

Content type
application/json
{
  • "error": {
    },
  • "forwarder": {
    },
  • "pointsUpdatedTime": "2019-08-24T14:15:22Z",
  • "queue": {
    },
  • "retry": {
    },
  • "runtimes": [
    ],
  • "scheduler": {
    },
  • "status": 0,
  • "totalCount": "string"
}

StopHook

Attempt to stop a running hook.

Stopping a running hook restarts the runtime process, and so all running invoations are aborted.

path Parameters
applicationId
required
string
hookId
required
string
pid
required
string

Responses

Response samples

Content type
application/json
{ }

GetHookLogs

path Parameters
applicationId
required
string
query Parameters
hookId
string
version
string

Responses

Response samples

Content type
application/json
{
  • "level": 0,
  • "message": "string",
  • "ts": "2019-08-24T14:15:22Z",
  • "version": "string"
}

RestartApplication

Restart application terminates any running runtime processes.

This should be called after writing new source files or calling InstallDependies to force the runtime to load the new source.

path Parameters
applicationId
required
string

Responses

Response samples

Content type
application/json
{ }

GetApplicationTimeSeries

path Parameters
applicationId
required
string
Request Body schema: application/json
applicationId
string
from
string <date-time>
hooks
Array of strings
object (ResampleOptions)
to
string <date-time>

Responses

Request samples

Content type
application/json
{
  • "applicationId": "string",
  • "from": "2019-08-24T14:15:22Z",
  • "hooks": [
    ],
  • "resample": {
    },
  • "to": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "hooks": [
    ]
}

UpgradeApplication

UpgradeApplication performs git pull if the application's Git URL is configured.

WARNING: This is equivalent to performing a hard reset against the remote branchs, so any local changes to the source will be lost.

path Parameters
applicationId
required
string
Request Body schema: application/json
applicationId
string

Responses

Request samples

Content type
application/json
{
  • "applicationId": "string"
}

Response samples

Content type
application/json
{ }

UpdateApplication

UpdateApplication allows updating configuration options defined by the application.

The available options are returned in the body of GetApplications.

path Parameters
id
required
string
Request Body schema: application/json
object (ApplicationAuth)
object

these set configuration values to no-default

gitUrl
string
id
string
object (Layer)
minNfVersion
string

Responses

Request samples

Content type
application/json
{
  • "auth": {
    },
  • "configuration": {
    },
  • "gitUrl": "string",
  • "id": "string",
  • "layer": {
    },
  • "minNfVersion": "string"
}

Response samples

Content type
application/json
{ }

GetApplications

An application wraps a number of hooks and other resources which run within the same runtime environment.

Each application shares a number of pieces: Runtime: there is a single runtime for an application Hook: an application can have multiple hooks with different definitions and run modes. Files: the application directory can have files with code or arbitary data. Git URL: applications may be backed by a git repository Options: an application may define options to allow the user to configure settings without needing to edit the application code.

path Parameters
name
required
string
query Parameters
pageSize
string
pageCount
string

Responses

Response samples

Content type
application/json
{
  • "applications": [
    ],
  • "totalCount": "string"
}

BACnet

The BACnet V2 service provides full access to the BACnet confirmed-service application layer. All services defined in BACnet-2020 are supported, and are compiled directly from the specification, including types for standard objects and enumerations. This allows the sophisticated user to interact with nearly any standards compliant BACnet device using teh ConfirmedService endpoint.

ConfirmedService

  • Make a confirmed service request and wait for the reply.
Request Body schema: application/json
object (DeviceAddress)

DeviceAddress. Specifies the full network address of a BACnet device.

object (OperationOptions)

Options that apply to the handling of a request within the stack.

object (ConfirmedServiceRequest)

Responses

Request samples

Content type
application/json
{
  • "deviceAddress": {
    },
  • "options": {
    },
  • "request": {
    }
}

Response samples

Content type
application/json
{
  • "SimpleAck": true,
  • "abort": 0,
  • "ack": {
    },
  • "error": {
    },
  • "reject": 0
}

Snoop

Responses

Response samples

Content type
application/json
{
  • "dst": {
    },
  • "pdu": {
    },
  • "src": {
    }
}

UnconfirmedHandler

  • BACnetUnconfirmedServiceHandlerReturns a stream of unconfirmed requests obtained by the server.

Responses

Response samples

Content type
application/json
{
  • "deviceAddress": {
    },
  • "request": {
    }
}

Bacnet

BACnet Service, version 1

The BACnet Service provides access to certain popular BACnet services at a low level of abstraction. However, unlike the BACnet V2 service, certain operations may be executed using equivalent operations in order to improve network performance. For instance, ReadProperty requests may be merged and executed using the ReadProperty-Multiple service if the underlying device support it.

AtomicReadFile

Read a file using the AtomicReadFile service

This function will return a stream of chunks of up to max_apdu size from the file specified in the request. The offset and length parameters can be used to perform partial reads on the file.

Only the stream access mode is supported.

The client must concatinate the resulting file by appending each chunk to a file

Request Body schema: application/json
object (ObjectIdentifier)
object (AtomicReadFileRequest_RecordAccess)
object (AtomicReadFileRequest_StreamAccess)

Responses

Request samples

Content type
application/json
{
  • "fileIdentifier": {
    },
  • "recordAccess": {
    },
  • "streamAccess": {
    }
}

Response samples

Content type
application/json
{
  • "data": "string",
  • "end": true,
  • "error": {
    }
}

ReadProperty

Execute a ReadProperty request against a BACnet device. This may be merged with other pending reads into a ReadPropMultiple.

query Parameters
deviceAddress.mac
string <bytes>
deviceAddress.net
integer <uint32>
deviceAddress.adr
string <bytes>
deviceAddress.maxApdu
integer <uint32>
deviceAddress.deviceId
integer <uint32>

if this is null we will use the wildcard

deviceAddress.bbmd
string <bytes>
deviceAddress.portId
integer <uint32>

the id of the network port the device is on. 0 = the default port (usually BACnet/IP)

objectId.objectType
integer <enum>
objectId.instance
integer <uint32>
propertyId
integer <enum>

property name

arrayIndex
integer <uint32>

array index, or null if not included.

options.timeout.seconds
string

Signed seconds of the span of time. Must be from -315,576,000,000 to +315,576,000,000 inclusive. Note: these bounds are computed from: 60 sec/min * 60 min/hr * 24 hr/day * 365.25 days/year * 10000 years

options.timeout.nanos
integer <int32>

Signed fractions of a second at nanosecond resolution of the span of time. Durations less than one second are represented with a 0 seconds field and a positive or negative nanos field. For durations of one second or more, a non-zero value for the nanos field must be of the same sign as the seconds field. Must be from -999,999,999 to +999,999,999 inclusive.

options.unmergeable
boolean

certain operations (reads) may be merged; set to false if you don't want this to happen.

options.priority
integer <int32>

priority level for scheduling. higher number is lower priority (like nice values)

options.continueOnError
boolean

if an operation has multiple components (like a ReadPropertyMultiple), wheather to return partial results and try on error.

options.blockLowerPriority
boolean

if true, cause other lower-priority operations to fail while this operation is being executed.

useFutureValues
boolean

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "futureValue": {
    },
  • "property": {
    },
  • "value": {
    }
}

ReadProperty

Execute a ReadProperty request against a BACnet device. This may be merged with other pending reads into a ReadPropMultiple.

Request Body schema: application/json
object (ObjectIdentifier)
propertyArrayIndex
integer <uint32>
propertyIdentifier
integer <enum>

Responses

Request samples

Content type
application/json
{
  • "objectIdentifier": {
    },
  • "propertyArrayIndex": 0,
  • "propertyIdentifier": 0
}

Response samples

Content type
application/json
{
  • "error": {
    },
  • "futureValue": {
    },
  • "property": {
    },
  • "value": {
    }
}

ReadPropMultiple

Read a list of properties from a single device.

This function does not map 1-1 onto BACnet operations; reads may be merged with other pending reads, split up due to APDU limits on the device or return cached data.

query Parameters
deviceAddress.mac
string <bytes>
deviceAddress.net
integer <uint32>
deviceAddress.adr
string <bytes>
deviceAddress.maxApdu
integer <uint32>
deviceAddress.deviceId
integer <uint32>

if this is null we will use the wildcard

deviceAddress.bbmd
string <bytes>
deviceAddress.portId
integer <uint32>

the id of the network port the device is on. 0 = the default port (usually BACnet/IP)

options.timeout.seconds
string

Signed seconds of the span of time. Must be from -315,576,000,000 to +315,576,000,000 inclusive. Note: these bounds are computed from: 60 sec/min * 60 min/hr * 24 hr/day * 365.25 days/year * 10000 years

options.timeout.nanos
integer <int32>

Signed fractions of a second at nanosecond resolution of the span of time. Durations less than one second are represented with a 0 seconds field and a positive or negative nanos field. For durations of one second or more, a non-zero value for the nanos field must be of the same sign as the seconds field. Must be from -999,999,999 to +999,999,999 inclusive.

options.unmergeable
boolean

certain operations (reads) may be merged; set to false if you don't want this to happen.

options.priority
integer <int32>

priority level for scheduling. higher number is lower priority (like nice values)

options.continueOnError
boolean

if an operation has multiple components (like a ReadPropertyMultiple), wheather to return partial results and try on error.

options.blockLowerPriority
boolean

if true, cause other lower-priority operations to fail while this operation is being executed.

useFutureValues
boolean

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "values": [
    ]
}

ReadPropMultiple

Read a list of properties from a single device.

This function does not map 1-1 onto BACnet operations; reads may be merged with other pending reads, split up due to APDU limits on the device or return cached data.

Request Body schema: application/json
object (DeviceAddress)

DeviceAddress. Specifies the full network address of a BACnet device.

object (OperationOptions)

Options that apply to the handling of a request within the stack.

Array of objects (ObjectPropertyReference)

a list of object and property referneces we want to read. in the BACnet RPM spec these are nested; but we flatten them out for simplicity.

useFutureValues
boolean

Responses

Request samples

Content type
application/json
{
  • "deviceAddress": {
    },
  • "options": {
    },
  • "readProperties": [
    ],
  • "useFutureValues": true
}

Response samples

Content type
application/json
{
  • "error": {
    },
  • "values": [
    ]
}

ReadRange

Perform a ReadRange request against the specified object; usually the Log_Buffer property of a Trend Log.

Only reading by absolution position or sequence nber are supported.

Request Body schema: application/json
object (ReadRangeRequest_ByPosition)
object (ReadRangeRequest_BySequenceNumber)
object (ReadRangeRequest_ByTime)
object (ObjectIdentifier)
propertyArrayIndex
integer <uint32>
propertyIdentifier
integer <enum>

Responses

Request samples

Content type
application/json
{
  • "byPosition": {
    },
  • "bySequenceNumber": {
    },
  • "byTime": {
    },
  • "objectIdentifier": {
    },
  • "propertyArrayIndex": 0,
  • "propertyIdentifier": 0
}

Response samples

Content type
application/json
{
  • "error": {
    },
  • "firstSequence": 0,
  • "itemCount": 0,
  • "records": [
    ]
}

WhoIs

Send a Who-Is request on the configured network, and stream the discovered devices until the timeout expires.

Request Body schema: application/json
deviceInstanceRangeHighLimit
integer <uint32>
deviceInstanceRangeLowLimit
integer <uint32>

Responses

Request samples

Content type
application/json
{
  • "deviceInstanceRangeHighLimit": 0,
  • "deviceInstanceRangeLowLimit": 0
}

Response samples

Content type
application/json
{
  • "deviceAddress": {
    }
}

WhoIsRouter

Send a WhoIsRouter request, and stream back replies until the timeout expires.

Request Body schema: application/json
mac
string <bytes>

optional, MAC to send the request two. if not set, sent to broadcast

net
integer <uint32>

optional, DNET if set

object (OperationOptions)

Options that apply to the handling of a request within the stack.

Responses

Request samples

Content type
application/json
{
  • "mac": "string",
  • "net": 0,
  • "options": {
    }
}

Response samples

Content type
application/json
{
  • "mac": "string",
  • "nets": [
    ]
}

WriteProperty

Write a single property. You may get an error if the right type is not used.

Request Body schema: application/json
object (ObjectIdentifier)
priority
integer <uint32>
propertyArrayIndex
integer <uint32>
propertyIdentifier
integer <enum>
object (GoogleProtobufAny)

Contains an arbitrary serialized message along with a @type that describes the type of the serialized message.

Responses

Request samples

Content type
application/json
{
  • "objectIdentifier": {
    },
  • "priority": 0,
  • "propertyArrayIndex": 0,
  • "propertyIdentifier": 0,
  • "propertyValue": {
    }
}

Response samples

Content type
application/json
{
  • "error": {
    }
}

CommandManager

The command service provides higher-level access to underlying device operations, including generic "Read" and "Write" operations. These operations encapsulate much of the device-specific code required in order to interact with field devices, such as retrieving BACnet network addresses from the Point service and submitting valid BACnet requests.

The command service also supports grouping multiple operations into command operations. Grouping operations allow Normal to perform expiration and reversion of write operations after a period of time, either by clearing an element in a priority array; or by writing back the original value.

GetCommands

GetCommands returns a list of active commands.

query Parameters
pageOffset
string
pageSize
string

Responses

Response samples

Content type
application/json
{
  • "commands": [
    ],
  • "totalCount": "string"
}

StartCommand

Start command initiates a new command for a set of points.

Request Body schema: application/json
object

alternatively, use a duration

expiresAt
string <date-time>

timestamp after which the writes should be undone

name
string

caller-provided name for the command. starting a command with an in-use name results in an error to provide a form of locking

Responses

Request samples

Content type
application/json
{
  • "duration": {
    },
  • "expiresAt": "2019-08-24T14:15:22Z",
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "expiresAt": "2019-08-24T14:15:22Z",
  • "id": "string"
}

Read

  • Read data from the underlying HPL. This operation includes looking up point references, grouping as required by the underlying layer (for instance, by separating reads by BACnet device); submitting the requests; and constructing an easy-to-use reply.
Request Body schema: application/json
Array of objects (PointRead)

Responses

Request samples

Content type
application/json
{
  • "reads": [
    ]
}

Response samples

Content type
application/json
{
  • "errors": [
    ],
  • "results": [
    ]
}

ObserveRawCommandActions

Returns a steram of "raw" actions (reads and writes) which were initiated by the comman subsystem. This forms an audit log of

query Parameters
layer
string
uuid
string
version
string
limit
integer <uint32>
wait
boolean
commandIds
Array of strings

Responses

Response samples

Content type
application/json
{
  • "action": 0,
  • "commandId": "string",
  • "error": {
    },
  • "point": {
    },
  • "ts": "2019-08-24T14:15:22Z",
  • "value": {
    },
  • "version": "string"
}

Write

Request Body schema: application/json
Array of objects (PointWrite)

Responses

Request samples

Content type
application/json
{
  • "writes": [
    ]
}

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

CancelCommand

Cancelling a command is the same as causing its lifetime to expire early. Points will be cleared if possible.

path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{ }

GetCommand

path Parameters
id
required
string
Request Body schema: application/json
id
string
name
string

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "command": {
    }
}

Configuration

GetConfiguration

GetConfiguration

Return the current configuration of the BACnet integration. This includes things like the list of available network interfaces.

Responses

Response samples

Content type
application/json
{
  • "automaticDiscoveryPeriod": {
    },
  • "backgroundScansEnabled": true,
  • "datalink": 0,
  • "debug": true,
  • "deviceInstance": 0,
  • "deviceName": "string",
  • "ip": {
    },
  • "sc": {
    },
  • "virtualNetworkNumber": 0
}

SetConfiguration

SetConfiguration

This can be used to change the default network interface, port, or configure a BBMD.

Request Body schema: application/json
object

if non-zero, NF will perform a global whois-based discovery each interval to find any additional devices

backgroundScansEnabled
boolean

when enabled, NF will rescan any devices if their

datalink
integer <enum>
debug
boolean

debug logging enabled

deviceInstance
integer <uint32>

instance number of the local device (device id)

deviceName
string

prop_object_name for the local device object

object (SetIPConfigurationRequest)
object (SCConfiguration)
virtualNetworkNumber
integer <uint32>

virtual network number

Responses

Request samples

Content type
application/json
{
  • "automaticDiscoveryPeriod": {
    },
  • "backgroundScansEnabled": true,
  • "datalink": 0,
  • "debug": true,
  • "deviceInstance": 0,
  • "deviceName": "string",
  • "ip": {
    },
  • "sc": {
    },
  • "virtualNetworkNumber": 0
}

Response samples

Content type
application/json
{ }

GetLocalObjects

GetLocalObjects

GetLocalObjects returns a list of all "local" objects available on the gateway, with the exception of the Device object (which can't be edited through this interface).

Each object consists of an object type / instance number as well as a list of property values which have been configured.

query Parameters
localDeviceInstanceOffset
integer <int32>

local device instance offset 0 for NF device -1 to retrieve all objects

Responses

Response samples

Content type
application/json
{
  • "objects": [
    ]
}

UpdateLocalObject

UpdateLocalObject

UpdateLocalObject allows you to change the value of a property on an existing object; or to create a new property.

Any updates to standard properties (like name or present-value) are type checked; it is an error to try to write an invalid type to one of these properties.

Request Body schema: application/json
localDeviceInstanceOffset
integer <uint32>
object (ObjectId)
Array of objects (PropertyValue)
uuid
string

Responses

Request samples

Content type
application/json
{
  • "localDeviceInstanceOffset": 0,
  • "objectId": {
    },
  • "props": [
    ],
  • "uuid": "string"
}

Response samples

Content type
application/json
{
  • "object": {
    }
}

CreateLocalObject

CreateLocalObject

CreateLocalObject creates a new object on the BACnet server instance controlled by NF. Local objects are persistent and available to other devices on the network.

In order to create an object, you must provide an BACnet object type, and any required properties. Supported object types are OBJECT_ANALOG_VALUE, OBJECT_BINARY_VALUE, and OBJECT_MULTI_STATE_VALUE.

When creating an object, you must provide any mandatory property values; for instance, for analog inputs, PROP_NAME and PROP_UNITS are both mandatory. Certain other properties required by the BACnet specification (like PROP_OUT_OF_SERVICE) will be added by default if you don't provide them.

Any mandatory or optional arguments must have the correct type -- for instance, the PRESENT_VALUE of an analog value must be of type real.

Request Body schema: application/json
localDeviceInstanceOffset
integer <uint32>
object

if instance is zero a new instance will be allocated

Array of objects (PropertyValue)
uuid
string

Responses

Request samples

Content type
application/json
{
  • "localDeviceInstanceOffset": 0,
  • "objectId": {
    },
  • "props": [
    ],
  • "uuid": "string"
}

Response samples

Content type
application/json
{
  • "objectId": {
    },
  • "uuid": "string"
}

DeleteLocalObject

DeleteLocalObject

DeleteLocalObject removes the specified object from the object database

path Parameters
object_id.object_type
required
string
object_id.instance
required
string
query Parameters
objectId.objectType
integer <enum>
objectId.instance
integer <uint32>
localDeviceInstanceOffset
integer <uint32>

Responses

Response samples

Content type
application/json
{ }

ObserveLocalObjectUpdates

query Parameters
version
string
limit
integer <int32>
wait
boolean

Responses

Response samples

Content type
application/json
{
  • "changeKind": 0,
  • "localDeviceInstanceOffset": 0,
  • "objectId": {
    },
  • "props": [
    ],
  • "ts": "2019-08-24T14:15:22Z",
  • "uuid": "string",
  • "version": "string"
}

Modbus

DeleteDeviceConnection

  • DeleteDeviceConnectionDelete a connection to a modbus device.This does not remove any points which have been created by the connection, which must be cleaned up separately if desired.
Request Body schema: application/json
uuid
string

Responses

Request samples

Content type
application/json
{
  • "uuid": "string"
}

Response samples

Content type
application/json
{ }

GetDeviceConnections

  • GetDeviceConnectionsGet all configured device connections.

Responses

Response samples

Content type
application/json
{
  • "connections": [
    ]
}

CreateDeviceConnection

  • CreateDeviceConnectionsCreate a connection to a new device using an existing profile.Note that after creating a connection, the polling rate must be configured using the point service before the service will begin acquiring data
Request Body schema: application/json
object (DeviceConnection)

Responses

Request samples

Content type
application/json
{
  • "connection": {
    }
}

Response samples

Content type
application/json
{
  • "connectionUuid": "string"
}

DeleteDeviceProfile

  • DeleteDeviceProfileDelete a device profile
Request Body schema: application/json
uuid
string

Responses

Request samples

Content type
application/json
{
  • "uuid": "string"
}

Response samples

Content type
application/json
{ }

GetDeviceProfiles

  • GetDeviceProfilesReturn a list of all configured modbus device profiles (pass content=1 to also get the register maps)You must provide a valid profile UUID when creating a connection to a device.
query Parameters
content
boolean

set to true to retrieve register maps

Responses

Response samples

Content type
application/json
{
  • "profiles": [
    ]
}

CreateDeviceProfile

  • CreateDeviceProfileCreate a new device profile to allow connecting to Modbus devices.
Request Body schema: application/json
object (DeviceProfile)

Responses

Request samples

Content type
application/json
{
  • "profile": {
    }
}

Response samples

Content type
application/json
{ }

PlatformConfig

GetEnvironmentVariables

query Parameters
name
string
section
string

Responses

Response samples

Content type
application/json
{
  • "variables": [
    ]
}

SetEnvironmentVariables

Request Body schema: application/json
Array of objects (EnvironmentVariable)

Responses

Request samples

Content type
application/json
{
  • "variables": [
    ]
}

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

GetSystemInformation

Responses

Response samples

Content type
application/json
{
  • "authority": "string",
  • "clientid": "string",
  • "domain": "string",
  • "enableAuth": true,
  • "favIcon": "string",
  • "footerText": "string",
  • "license": {
    },
  • "logo": "string",
  • "machineInfo": "string",
  • "provider": 0,
  • "scopes": "string",
  • "services": [
    ],
  • "siteName": "string",
  • "thumbnail": "string",
  • "version": "string"
}

SetLicense

Request Body schema: application/json
license
string

Responses

Request samples

Content type
application/json
{
  • "license": "string"
}

Response samples

Content type
application/json
{ }

PointManager

Point Service

The point service is the main interface into the configuration state stored on the device. It provides:

  • Efficient full-text search of all objects on the device

AggregatePoints

Request Body schema: application/json
Array of objects (PointAggregator)

aggregators to apply

attrs
Array of strings

attributes to group by

layer
string
object

optional query to filter rows

Responses

Request samples

Content type
application/json
{
  • "aggregators": [
    ],
  • "attrs": [
    ],
  • "layer": "string",
  • "query": {
    }
}

Response samples

Content type
application/json
{
  • "values": [
    ]
}

GetDistinctAttrs

GetDistinctAttrs

Return a list of distinct values and counts for the given list of attributes. For instance, you can use this to generate a list of filters, or find all of the different object names, vendors, or software revisions. The attributes do not need to be indexed in the layer.

If a query is provided, perform a database scan to compute attribute counts instead of using the precomputed values. This may be slow but allows more advanced use cases.

query Parameters
attrs
Array of strings
query
string
structuredQuery.field.property
string
structuredQuery.field.text
string
structuredQuery.field.numeric.minValue
number <double>
structuredQuery.field.numeric.minInfinity
boolean
structuredQuery.field.numeric.maxValue
number <double>
structuredQuery.field.numeric.maxInfinity
boolean
structuredQuery.field.layer
string
structuredQuery.field.wildcard
boolean
structuredQuery.reference.property
string
structuredQuery.reference.targetProperty
string
structuredQuery.reference.query.field.property
string
structuredQuery.reference.query.field.text
string
structuredQuery.reference.query.field.numeric.minValue
number <double>
structuredQuery.reference.query.field.numeric.minInfinity
boolean
structuredQuery.reference.query.field.numeric.maxValue
number <double>
structuredQuery.reference.query.field.numeric.maxInfinity
boolean
structuredQuery.reference.query.field.layer
string
structuredQuery.reference.query.field.wildcard
boolean
structuredQuery.reference.query.reference.property
string
structuredQuery.reference.query.reference.targetProperty
string
layer
string
queryLayer
string
pageOffset
string
pageSize
string

Responses

Response samples

Content type
application/json
{
  • "attrs": [
    ]
}

DeleteConfigKeys

query Parameters
keys
Array of strings

Responses

Response samples

Content type
application/json
{
  • "keys": [
    ]
}

GetConfigKeys

query Parameters
keys
Array of strings

Responses

Response samples

Content type
application/json
{
  • "values": {
    }
}

SetConfigKey

Request Body schema: application/json
key
string
value
string <bytes>

Responses

Request samples

Content type
application/json
{
  • "key": "string",
  • "value": "string"
}

Response samples

Content type
application/json
{ }

CopyAttributes

Request Body schema: application/json
attributes
Array of strings

list of attribute names to copy

object

if present, update the COV settings

indexLayer
string

layer to perform search query against. if blank, the input layer is used.

inputLayer
string

layer to read values from. may be a base layer

mappedAttributes
Array of strings

if present, a list of corresponding attribute names to map in the output layer

outputLayer
string

layer to write values to. may be a base layer

object

if present, update the matching points with this period

query
string

the copy operation is applied to all points matching the query or in the list of uuids

object

any attributes set here will be set to the static value in the map instead of the input layer value. if all attributes are in the map, the input layer is ignored and may be blank, and only the output layer is written to. this can be used, for instance, to set an attribute to a constant text string based on a query, or to clear an attribute.

object (Query)
uuids
Array of strings

any UUIDs specified in this list are also consider matched.

Responses

Request samples

Content type
application/json
{
  • "attributes": [
    ],
  • "cov": {
    },
  • "indexLayer": "string",
  • "inputLayer": "string",
  • "mappedAttributes": [
    ],
  • "outputLayer": "string",
  • "period": {
    },
  • "query": "string",
  • "staticAttributes": {
    },
  • "structuredQuery": {
    },
  • "uuids": [
    ]
}

Response samples

Content type
application/json
{
  • "updateCount": 0
}

GetData

GetData

GetData queries the time series data available on the device. Note the default retention period for in-memory data is one week.

query Parameters
layer
string

Not used starting from 3.0

uuids
Array of strings
from.seconds
string

Represents seconds of UTC time since Unix epoch 1970-01-01T00:00:00Z. Must be from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59Z inclusive.

from.nanos
integer <int32>

Non-negative fractions of a second at nanosecond resolution. Negative second values with fractions must still have non-negative nanos values that count forward in time. Must be from 0 to 999,999,999 inclusive.

to.seconds
string

Represents seconds of UTC time since Unix epoch 1970-01-01T00:00:00Z. Must be from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59Z inclusive.

to.nanos
integer <int32>

Non-negative fractions of a second at nanosecond resolution. Negative second values with fractions must still have non-negative nanos values that count forward in time. Must be from 0 to 999,999,999 inclusive.

window.seconds
string

Signed seconds of the span of time. Must be from -315,576,000,000 to +315,576,000,000 inclusive. Note: these bounds are computed from: 60 sec/min * 60 min/hr * 24 hr/day * 365.25 days/year * 10000 years

window.nanos
integer <int32>

Signed fractions of a second at nanosecond resolution of the span of time. Durations less than one second are represented with a 0 seconds field and a positive or negative nanos field. For durations of one second or more, a non-zero value for the nanos field must be of the same sign as the seconds field. Must be from -999,999,999 to +999,999,999 inclusive.

method
integer <enum>
errorData
boolean

if true, return data from the error series and not the data series

count
integer <int32>
reverse
boolean

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

AddPointsData

AddPointsData

This endpoint adds timeseries and error data to the stream.

Request Body schema: application/json
Array of objects (Error)
isAsync
boolean
layer
string

Not used starting from 3.0

uuid
string
Array of objects (Value)

Responses

Request samples

Content type
application/json
{
  • "errors": [
    ],
  • "isAsync": true,
  • "layer": "string",
  • "uuid": "string",
  • "values": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true,
  • "taskUuid": "string"
}

GetPointErrors

GetPointErrors

GetPointErrors Note the default retention number is 5 last errors

query Parameters
uuids
Array of strings

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

CreateExport

query Parameters
layer
string

layer to export

structuredQuery.field.property
string
structuredQuery.field.text
string
structuredQuery.field.numeric.minValue
number <double>
structuredQuery.field.numeric.minInfinity
boolean
structuredQuery.field.numeric.maxValue
number <double>
structuredQuery.field.numeric.maxInfinity
boolean
structuredQuery.field.layer
string
structuredQuery.field.wildcard
boolean
structuredQuery.reference.property
string
structuredQuery.reference.targetProperty
string
structuredQuery.reference.query.field.property
string
structuredQuery.reference.query.field.text
string
structuredQuery.reference.query.field.numeric.minValue
number <double>
structuredQuery.reference.query.field.numeric.minInfinity
boolean
structuredQuery.reference.query.field.numeric.maxValue
number <double>
structuredQuery.reference.query.field.numeric.maxInfinity
boolean
structuredQuery.reference.query.field.layer
string
structuredQuery.reference.query.field.wildcard
boolean
structuredQuery.reference.query.reference.property
string
structuredQuery.reference.query.reference.targetProperty
string
masks.attrIncludeMask
Array of strings

applies to attributes: if blank

masks.attrExcludeMask
Array of strings
masks.fieldMask
Array of strings

applies to proto fields

masks.fieldExcludeMask
Array of strings
format
integer <enum>

format

Responses

Response samples

Content type
application/json
{
  • "downloadPath": "string"
}

GetDistinctAttrKeys

GetDistinctAttrKeys

Return a list of distinct attribute keys, and the number of points which have each attribute set to a non-blank value in the given layer.

If the attribute list is passed, counts are only returned for the requested key names.

query Parameters
attrs
Array of strings
query
string
structuredQuery.field.property
string
structuredQuery.field.text
string
structuredQuery.field.numeric.minValue
number <double>
structuredQuery.field.numeric.minInfinity
boolean
structuredQuery.field.numeric.maxValue
number <double>
structuredQuery.field.numeric.maxInfinity
boolean
structuredQuery.field.layer
string
structuredQuery.field.wildcard
boolean
structuredQuery.reference.property
string
structuredQuery.reference.targetProperty
string
structuredQuery.reference.query.field.property
string
structuredQuery.reference.query.field.text
string
structuredQuery.reference.query.field.numeric.minValue
number <double>
structuredQuery.reference.query.field.numeric.minInfinity
boolean
structuredQuery.reference.query.field.numeric.maxValue
number <double>
structuredQuery.reference.query.field.numeric.maxInfinity
boolean
structuredQuery.reference.query.field.layer
string
structuredQuery.reference.query.field.wildcard
boolean
structuredQuery.reference.query.reference.property
string
structuredQuery.reference.query.reference.targetProperty
string
layer
string
queryLayer
string
pageOffset
string
pageSize
string

Responses

Response samples

Content type
application/json
{
  • "attrs": [
    ]
}

GetLayers

GetLayers

Return the list of available layers.

query Parameters
name
string

Responses

Response samples

Content type
application/json
{
  • "layers": [
    ],
  • "totalCount": "string"
}

CreateLayer

CreateLayer

Create a new layer of either kind (BASE or UNION). The layer request should be complete with the name and kind of the layer, if it should be indexed, and the names of any component fields or sublayers.

Request Body schema: application/json
object (Layer)

Responses

Request samples

Content type
application/json
{
  • "layer": {
    }
}

Response samples

Content type
application/json
{ }

DeleteLayer

DeleteLayer

Delete a layer from the system. If delete_points is false, only the name of the layer and associated indexes will be removed; however any underlying points and timeseries will be left. If delete_points is true, any point metadata and timeseries associated with the layer will also be removed, and the count of deleted points returned to the client.

path Parameters
name
required
string

Responses

Response samples

Content type
application/json
{ }

GetLayers

GetLayers

Return the list of available layers.

path Parameters
name
required
string

Responses

Response samples

Content type
application/json
{
  • "layers": [
    ],
  • "totalCount": "string"
}

DeletePoints

DeletePoints

Remove the point object and any underlying data from the system. This does not remove data from the update log.

query Parameters
layers
Array of strings

points will be deleted in these layers. you can only delete points from a base layer. if the list is empty, the point will be deleted in all payers

uuids
Array of strings

delete these uuids

indexLayer
string

delete points matching this query

structuredQuery.field.property
string
structuredQuery.field.text
string
structuredQuery.field.numeric.minValue
number <double>
structuredQuery.field.numeric.minInfinity
boolean
structuredQuery.field.numeric.maxValue
number <double>
structuredQuery.field.numeric.maxInfinity
boolean
structuredQuery.field.layer
string
structuredQuery.field.wildcard
boolean
structuredQuery.reference.property
string
structuredQuery.reference.targetProperty
string
structuredQuery.reference.query.field.property
string
structuredQuery.reference.query.field.text
string
structuredQuery.reference.query.field.numeric.minValue
number <double>
structuredQuery.reference.query.field.numeric.minInfinity
boolean
structuredQuery.reference.query.field.numeric.maxValue
number <double>
structuredQuery.reference.query.field.numeric.maxInfinity
boolean
structuredQuery.reference.query.field.layer
string
structuredQuery.reference.query.field.wildcard
boolean
structuredQuery.reference.query.reference.property
string
structuredQuery.reference.query.reference.targetProperty
string

Responses

Response samples

Content type
application/json
{
  • "deleteCount": "string"
}

GetPoints

GetPoints

Perform a search for points using the full-text search. In order to be in the search index, the layer must configure the index. You may retrieve these using GetLayers. For instance, the BACnet layer hpl:bacnet:1 indexes the following fields:

  • uuid
  • attr_device_id BACnet device id
  • attr_type BACnet object type
  • attr_instance BACnet object instance
  • attr_prop_units BACnet units (numeric enum value)
  • attr_prop_object_name BACnet object name
  • attr_prop_description BACnet description
  • period polling rate, in seconds
Request Body schema: application/json
Array of objects (Annotation)
layer
string

which layer to query the index on

object (PointMask)
pageOffset
string

pagination options

pageSize
string
query
string

text query to search for in the database deprecated in 1.6; use structured_query instead

responseFormat
integer <enum>
resultLayer
string

if set, only return results which are from this layer. this impacts the behavior of the pagination fields, since since these are applied first during the query lookup. However, it can be used to query keys which appear in multiple layers without duplicates

object (Sort)
sortField
string
sortOrder
string
object (Query)

Responses

Request samples

Content type
application/json
{
  • "annotations": [
    ],
  • "layer": "string",
  • "masks": {
    },
  • "pageOffset": "string",
  • "pageSize": "string",
  • "query": "string",
  • "responseFormat": 0,
  • "resultLayer": "string",
  • "sort": {
    },
  • "sortField": "string",
  • "sortOrder": "string",
  • "structuredQuery": {
    }
}

Response samples

Content type
application/json
{
  • "points": [
    ],
  • "totalCount": "string"
}

UpdatePoints

UpdatePoints

Create or update points objects. If verion is nil, will be treated as a create and will fail if the uuid already exists. if the version is not nil, will succeed only if the database version matches the version provided.

One common use case of this is to configure polling, by editing the "period" field.

Request Body schema: application/json
isAsync
boolean
Array of objects (Point)

Update points in the database. The UUID is mandatory. Other fields will be updated if not null.

Responses

Request samples

Content type
application/json
{
  • "isAsync": true,
  • "points": [
    ]
}

Response samples

Content type
application/json
{
  • "results": [
    ]
}

GetPointsById

GetPointsById

Lookup points by UUID. The reply format is the same as GetPoints, but pagination and sorting are not supported.

query Parameters
layer
string
uuids
Array of strings
responseFormat
integer <enum>
masks.attrIncludeMask
Array of strings

applies to attributes: if blank

masks.attrExcludeMask
Array of strings
masks.fieldMask
Array of strings

applies to proto fields

masks.fieldExcludeMask
Array of strings

Responses

Response samples

Content type
application/json
{
  • "points": [
    ],
  • "totalCount": "string"
}

GetPoints

GetPoints

Perform a search for points using the full-text search. In order to be in the search index, the layer must configure the index. You may retrieve these using GetLayers. For instance, the BACnet layer hpl:bacnet:1 indexes the following fields:

  • uuid
  • attr_device_id BACnet device id
  • attr_type BACnet object type
  • attr_instance BACnet object instance
  • attr_prop_units BACnet units (numeric enum value)
  • attr_prop_object_name BACnet object name
  • attr_prop_description BACnet description
  • period polling rate, in seconds
query Parameters
layer
string

which layer to query the index on

resultLayer
string

if set, only return results which are from this layer. this impacts the behavior of the pagination fields, since since these are applied first during the query lookup. However, it can be used to query keys which appear in multiple layers without duplicates

query
string

text query to search for in the database deprecated in 1.6; use structured_query instead

structuredQuery.field.property
string
structuredQuery.field.text
string
structuredQuery.field.numeric.minValue
number <double>
structuredQuery.field.numeric.minInfinity
boolean
structuredQuery.field.numeric.maxValue
number <double>
structuredQuery.field.numeric.maxInfinity
boolean
structuredQuery.field.layer
string
structuredQuery.field.wildcard
boolean
structuredQuery.reference.property
string
structuredQuery.reference.targetProperty
string
structuredQuery.reference.query.field.property
string
structuredQuery.reference.query.field.text
string
structuredQuery.reference.query.field.numeric.minValue
number <double>
structuredQuery.reference.query.field.numeric.minInfinity
boolean
structuredQuery.reference.query.field.numeric.maxValue
number <double>
structuredQuery.reference.query.field.numeric.maxInfinity
boolean
structuredQuery.reference.query.field.layer
string
structuredQuery.reference.query.field.wildcard
boolean
structuredQuery.reference.query.reference.property
string
structuredQuery.reference.query.reference.targetProperty
string
responseFormat
integer <enum>
masks.attrIncludeMask
Array of strings

applies to attributes: if blank

masks.attrExcludeMask
Array of strings
masks.fieldMask
Array of strings

applies to proto fields

masks.fieldExcludeMask
Array of strings
pageOffset
string

pagination options

pageSize
string
sortField
string
sortOrder
string
sort.field
string
sort.order
string
sort.layer
string

Responses

Response samples

Content type
application/json
{
  • "points": [
    ],
  • "totalCount": "string"
}

RenamePoint

RenamePoint

Change the UUID of a point, preserving all time series data. ObservePointsUpdate will send consumers an update record with the old and new UUIDs; however, Not all consumers may expect this so this can be what disruptive.

Request Body schema: application/json
layer
string
newUuid
string
oldUuid
string

Responses

Request samples

Content type
application/json
{
  • "layer": "string",
  • "newUuid": "string",
  • "oldUuid": "string"
}

Response samples

Content type
application/json
{ }

GetDataSummary

GetDataSummary

Look up statistics about the data storted for a point.

query Parameters
layer
string
uuids
Array of strings
from.seconds
string

Represents seconds of UTC time since Unix epoch 1970-01-01T00:00:00Z. Must be from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59Z inclusive.

from.nanos
integer <int32>

Non-negative fractions of a second at nanosecond resolution. Negative second values with fractions must still have non-negative nanos values that count forward in time. Must be from 0 to 999,999,999 inclusive.

to.seconds
string

Represents seconds of UTC time since Unix epoch 1970-01-01T00:00:00Z. Must be from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59Z inclusive.

to.nanos
integer <int32>

Non-negative fractions of a second at nanosecond resolution. Negative second values with fractions must still have non-negative nanos values that count forward in time. Must be from 0 to 999,999,999 inclusive.

bucketEdges
Array of numbers <float> [ items <float > ]

if not empty, bucket edges for the histogram. can be used to use the same edges for all points in the request

bucketCount
integer <uint32>

Responses

Response samples

Content type
application/json
{
  • "summaries": [
    ]
}

DeleteTags

Request Body schema: application/json
layer
string
Array of objects (Tag)
uuids
Array of strings

Responses

Request samples

Content type
application/json
{
  • "layer": "string",
  • "tags": [
    ],
  • "uuids": [
    ]
}

Response samples

Content type
application/json
{ }

AddTags

AddTags

Add tags allows you to edit tag fields without implementing the read-modify-write update on the client. A tag field is any key which holds a comma-separated list of tag values. For instance, you can have a field named "haystack" with the value "air,sensor". When set as a tag field, NF will interpret that field as having tags "air" and "sensor", instead of as one value.

Using AddTags to update this field allow you to maniulate these tags directly, to avoid adding duplicate copies of tag values.

Request Body schema: application/json
layer
string
Array of objects (Tag)
uuids
Array of strings

Responses

Request samples

Content type
application/json
{
  • "layer": "string",
  • "tags": [
    ],
  • "uuids": [
    ]
}

Response samples

Content type
application/json
{ }

ObserveDataUpdates

ObserveDataUpdates

Streaming method for obtaining values. This can be used either for real-time use or for reliably archiving readings.

Although it is possible to construct a timeseries from this data, this interface is primarily designed to stream all data to another database. The default retention period for this interface is one month, and data are stored sequentially on disk.

If withMetadata is set, each data point will also include the point object's metadata. An important detail is that the metadata is not logged at the time of data collection, but retrieved when the value is sent to the consumer; so metadata changes may not be accurately reflected. If this will cause a problem, consumers should also consume ObservePointsUpdates to identify when metadata has changed.

query Parameters
layer
string
uuids
Array of strings
version
string
limit
integer <int32>
wait
boolean

weather to wait for new records

withMetadata
boolean

if point metadata should be included with each reply value.

structuredQuery.field.property
string
structuredQuery.field.text
string
structuredQuery.field.numeric.minValue
number <double>
structuredQuery.field.numeric.minInfinity
boolean
structuredQuery.field.numeric.maxValue
number <double>
structuredQuery.field.numeric.maxInfinity
boolean
structuredQuery.field.layer
string
structuredQuery.field.wildcard
boolean
structuredQuery.reference.property
string
structuredQuery.reference.targetProperty
string
structuredQuery.reference.query.field.property
string
structuredQuery.reference.query.field.text
string
structuredQuery.reference.query.field.numeric.minValue
number <double>
structuredQuery.reference.query.field.numeric.minInfinity
boolean
structuredQuery.reference.query.field.numeric.maxValue
number <double>
structuredQuery.reference.query.field.numeric.maxInfinity
boolean
structuredQuery.reference.query.field.layer
string
structuredQuery.reference.query.field.wildcard
boolean
structuredQuery.reference.query.reference.property
string
structuredQuery.reference.query.reference.targetProperty
string

Responses

Response samples

Content type
application/json
{
  • "layer": "string",
  • "point": {
    },
  • "type": 0,
  • "uuid": "string",
  • "value": {
    },
  • "version": "string"
}

ObserveErrorUpdates

ObserveErrorUpdates

Streaming method for reading back errors encountered during polling. Errors are stored sequentially on disk, and the default retention period is one month.

query Parameters
layer
string
uuids
Array of strings
version
string
limit
integer <int32>
wait
boolean

weather to wait for new records

withMetadata
boolean
structuredQuery.field.property
string
structuredQuery.field.text
string
structuredQuery.field.numeric.minValue
number <double>
structuredQuery.field.numeric.minInfinity
boolean
structuredQuery.field.numeric.maxValue
number <double>
structuredQuery.field.numeric.maxInfinity
boolean
structuredQuery.field.layer
string
structuredQuery.field.wildcard
boolean
structuredQuery.reference.property
string
structuredQuery.reference.targetProperty
string
structuredQuery.reference.query.field.property
string
structuredQuery.reference.query.field.text
string
structuredQuery.reference.query.field.numeric.minValue
number <double>
structuredQuery.reference.query.field.numeric.minInfinity
boolean
structuredQuery.reference.query.field.numeric.maxValue
number <double>
structuredQuery.reference.query.field.numeric.maxInfinity
boolean
structuredQuery.reference.query.field.layer
string
structuredQuery.reference.query.field.wildcard
boolean
structuredQuery.reference.query.reference.property
string
structuredQuery.reference.query.reference.targetProperty
string

Responses

Response samples

Content type
application/json
{
  • "error": {
    },
  • "layer": "string",
  • "point": {
    },
  • "uuid": "string",
  • "version": "string"
}

ObservePointsUpdates

ObservePointsUpdates

Streaming method for obtaining a stream of changes to the object database. Each record contains the old and new version of the object, which can be compared. For new objects, the "old" field is nil; while for deleted objects, the "new" field is nil.

When used with the REST API, the version, limit, and wait parameters can be used to read chunks of the change log. The first version is always 0-0, and so the log can be read back in chunks by starting with this version and then providing the last version received until no more records are obtained. By default the method returns records starting at the current head of the log.

  • version the version number to begin reading at
  • layer only return data from this layer
  • limit how many changes to write to the stream before closing the connection.
  • wait if the consumer should wait for new records once the head of the log is encountered. Not recommended for use with the REST api.
query Parameters
layer
string

only include updates for a particular layer

uuids
Array of strings

only include updates for a set of uuids

version
string

only retrieve changes since this version

limit
integer <int32>

how many records to send before closing the connection. if zero, never close the connection.

wait
boolean

whether to wait for new records

structuredQuery.field.property
string
structuredQuery.field.text
string
structuredQuery.field.numeric.minValue
number <double>
structuredQuery.field.numeric.minInfinity
boolean
structuredQuery.field.numeric.maxValue
number <double>
structuredQuery.field.numeric.maxInfinity
boolean
structuredQuery.field.layer
string
structuredQuery.field.wildcard
boolean
structuredQuery.reference.property
string
structuredQuery.reference.targetProperty
string
structuredQuery.reference.query.field.property
string
structuredQuery.reference.query.field.text
string
structuredQuery.reference.query.field.numeric.minValue
number <double>
structuredQuery.reference.query.field.numeric.minInfinity
boolean
structuredQuery.reference.query.field.numeric.maxValue
number <double>
structuredQuery.reference.query.field.numeric.maxInfinity
boolean
structuredQuery.reference.query.field.layer
string
structuredQuery.reference.query.field.wildcard
boolean
structuredQuery.reference.query.reference.property
string
structuredQuery.reference.query.reference.targetProperty
string

Responses

Response samples

Content type
application/json
{
  • "fields": [
    ],
  • "layers": [
    ],
  • "new": {
    },
  • "old": {
    },
  • "ts": "2019-08-24T14:15:22Z",
  • "version": "string"
}

Scan

The BACnet scan services performs device discovery for the BACnet subsystem. This includes network and device scans, periodic rescans, the tracking of device database state, and managing the import of objects into the points database.

GetRenamedDevices

query Parameters
pageOffset
string
pageCount
string

Responses

Response samples

Content type
application/json
{
  • "renamed": [
    ],
  • "totalCount": "string"
}

RenameDevice

Renaming a BACnet devices creates a mapping from [old device UUID] to [new device UUID], causing points with the same type an instance number to receive the same uuid as they would have on the previous device.

Request Body schema: application/json
newUuid
string

the device uuid

oldUuid
string

the old device uuid

updateNewPoints
boolean

if we should find all points with uuids based on the old namespace and update them to point at the new namespace.

Responses

Request samples

Content type
application/json
{
  • "newUuid": "string",
  • "oldUuid": "string",
  • "updateNewPoints": true
}

Response samples

Content type
application/json
{
  • "pointsRenamed": "string"
}

DeleteRenamedDevice

path Parameters
oldUuid
required
string

Responses

Response samples

Content type
application/json
{ }

RestartJobs

Restart jobs is a simple way to resubmit jobs which may have failed / been canceled.

A new job is created with the same arguments as the original job had.

Request Body schema: application/json
ids
Array of integers <uint32> [ items <uint32 > ]

Responses

Request samples

Content type
application/json
{
  • "ids": [
    ]
}

Response samples

Content type
application/json
{
  • "ids": [
    ]
}

GetJobs

Retrieve jobs which have been submitted by StartJob

The StartJob request message allows a client to sort, filter and paginate the jobs based on Job ID.

query Parameters
statusFilter
integer <enum>
idFilter
integer <uint32>
parentIdFilter
integer <uint32>
typeFilter
string
deviceFilter
string
full
boolean
sortField
string

supports id, status, queued_at,

sortOrder
string

ASC or DESC

pageOffset
string
pageSize
string

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "totalCount": "string"
}

StartJob

Add a new job to the Job queue. Only one of the device, object, or network scans must be specified.

Request Body schema: application/json
autoImport
boolean
object (Duration)

A Duration represents a signed, fixed-length span of time represented as a count of seconds and fractions of seconds at nanosecond resolution. It is independent of any calendar and concepts like "day" or "month". It is related to Timestamp in that the difference between two Timestamp values is a Duration and it can be added or subtracted from a Timestamp. Range is approximately +-10,000 years. # Examples Example 1: Compute Duration from two Timestamps in pseudo code. Timestamp start = ...; Timestamp end = ...; Duration duration = ...; duration.seconds = end.seconds - start.seconds; duration.nanos = end.nanos - start.nanos; if (duration.seconds < 0 && duration.nanos > 0) { duration.seconds += 1; duration.nanos -= 1000000000; } else if (duration.seconds > 0 && duration.nanos < 0) { duration.seconds -= 1; duration.nanos += 1000000000; } Example 2: Compute Timestamp from Timestamp + Duration in pseudo code. Timestamp start = ...; Duration duration = ...; Timestamp end = ...; end.seconds = start.seconds + duration.seconds; end.nanos = start.nanos + duration.nanos; if (end.nanos < 0) { end.seconds -= 1; end.nanos += 1000000000; } else if (end.nanos >= 1000000000) { end.seconds += 1; end.nanos -= 1000000000; } Example 3: Compute Duration from datetime.timedelta in Python. td = datetime.timedelta(days=3, minutes=10) duration = Duration() duration.FromTimedelta(td) # JSON Mapping In JSON format, the Duration type is encoded as a string rather than an object, where the string ends in the suffix "s" (indicating seconds) and is preceded by the number of seconds, with nanoseconds expressed as fractional seconds. For example, 3 seconds with 0 nanoseconds should be encoded in JSON format as "3s", while 3 seconds and 1 nanosecond should be expressed in JSON format as "3.000000001s", and 3 seconds and 1 microsecond should be expressed in JSON format as "3.000001s".

clientId
string
object (DeviceScanJob)

Device Scan Jobs find BACnet servers (device objects) on the network and obtain a basic set of properties from them.

object (NetworkScanJob)

One must be somewhat careful since it is easy enough to simulate a denial of service attack with this tool.

object (ObjectScanJob)

Object Scan Jobs look at existing BACnet servers and read out their object list.

parentId
integer <uint32>

Responses

Request samples

Content type
application/json
{
  • "autoImport": true,
  • "autoPoll": {
    },
  • "clientId": "string",
  • "device": {
    },
  • "network": {
    },
  • "object": {
    },
  • "parentId": 0
}

Response samples

Content type
application/json
{
  • "autoImport": true,
  • "autoPoll": {
    },
  • "clientId": "string",
  • "device": {
    },
  • "deviceResult": [
    ],
  • "id": 0,
  • "imported": true,
  • "network": {
    },
  • "object": {
    },
  • "objectCount": {
    },
  • "objectResult": [
    ],
  • "parentId": 0,
  • "status": 0,
  • "statusMessage": "string",
  • "timestamps": {
    }
}

GetScanDeltas

Get a stream of object scan deltas.

This interface returns a stream of scan results with the changes (created/updated/deleted) devices and objects provided. This makes it easy to build visualizations and other interfaces which track the network state over time. The stream is closed after all scans have been sent.

The first record for a device / object is guaranteed to be a create so you can replicate the current state of the network by replaying these deltas.

query Parameters
version
string

If set, start scanning for deltas at a particular scan version

sinceTime.seconds
string

Represents seconds of UTC time since Unix epoch 1970-01-01T00:00:00Z. Must be from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59Z inclusive.

sinceTime.nanos
integer <int32>

Non-negative fractions of a second at nanosecond resolution. Negative second values with fractions must still have non-negative nanos values that count forward in time. Must be from 0 to 999,999,999 inclusive.

deviceId
Array of integers <uint32> [ items <uint32 > ]

filter object scans to only include the set of included device ids.

objectOnly
boolean

only send object deltas

deviceOnly
boolean

only send device deltas

Responses

Response samples

Content type
application/json
{
  • "deviceDelta": {
    },
  • "jobId": 0,
  • "objectDelta": {
    },
  • "version": "string"
}

ObserveJobUpdates

Listen to a stream of completed jobs.

This interface returns a stream of jobs which have ended (either succeded or failed). This allows downstream clients to synchronize object databases with this system without missing any records.

The call returns onces all available scans have been sent.

query Parameters
version
string

Sync token to only request new jobs. If nil or empty, will return all jobs available (since the beginning of time). Since the job stream may expire jobs due to memory pressures you may not be sure this is all jobs; use GetJobs.

limit
integer <int32>
wait
boolean
full
boolean

Responses

Response samples

Content type
application/json
{
  • "job": {
    },
  • "version": "string"
}

Status

The Device Status service monitors the error rates of devices, and provides device health statistics to consumers.

GetDeviceStatus

query Parameters
layer
string
errorFilter
integer <enum>

only return devices with a particular error status

returnTimeseries
boolean

return the error timeseries in addition to the current values

sortField
string

possibilities are last_alive or current_error_rate

sortOrder
string
pageOffset
string
pageSize
string

Responses

Response samples

Content type
application/json
{
  • "errorHistory": [
    ],
  • "results": [
    ],
  • "totalCount": "string"
}

GetErrorSummary

query Parameters
layer
string
deviceUuid
string
window.seconds
string

Signed seconds of the span of time. Must be from -315,576,000,000 to +315,576,000,000 inclusive. Note: these bounds are computed from: 60 sec/min * 60 min/hr * 24 hr/day * 365.25 days/year * 10000 years

window.nanos
integer <int32>

Signed fractions of a second at nanosecond resolution of the span of time. Durations less than one second are represented with a 0 seconds field and a positive or negative nanos field. For durations of one second or more, a non-zero value for the nanos field must be of the same sign as the seconds field. Must be from -999,999,999 to +999,999,999 inclusive.

Responses

Response samples

Content type
application/json
{
  • "deviceErrors": [
    ],
  • "errorCounts": {
    }
}