| Title: | Bindings for Onboard Data's Building Data API |
|---|---|
| Description: | Provides a wrapper for the Onboard Data building data API <https://api.onboarddata.io/swagger>. Along with streamlining access to the API, this package simplifies access to sensor time series data, metadata (sensors, equipment, and buildings), and details about the Onboard data model/ontology. |
| Authors: | Pranay Shah [aut], Christopher Dudas-Thomas [cre, aut], Onboard Data [cph, fnd] |
| Maintainer: | Christopher Dudas-Thomas <[email protected]> |
| License: | Apache License (>= 2) |
| Version: | 1.0.0 |
| Built: | 2024-12-06 06:30:25 UTC |
| Source: | CRAN |
Returns the API url and API key.
api.access()api.access()
A named list of API information, containing elements 'url' and 'key'.
Uses http GET call to return an object from the API.
api.get(endpoint)api.get(endpoint)
endpoint |
A character string containing a valid Onboard API endpoint. |
A list or data.frame of the API output.
## Not run: whoami <- api.get('whoami')## Not run: whoami <- api.get('whoami')
Uses http POST call to post objects to the API.
api.post(endpoint, json_body, output = "list")api.post(endpoint, json_body, output = "list")
endpoint |
A character string containing a valid Onboard API endpoint. |
json_body |
A JSON payload to give to the POST call. |
output |
A character string, either "list" (default) or "dataframe", to specify the API output format. |
A list or data.frame of the API output.
Set the Onboard API URL and API keys in the system environment.
api.setup(api_type = "prod")api.setup(api_type = "prod")
api_type |
Provide the API client name. |
No return value, sets API url and API key in the system environment.
Provides a status code and message for the API connection.
api.status()api.status()
A character string of the API server status and message.
Retrieves building id(s) and name(s). Assigns each to list variables in the parent environment called "id" and "name", and prints each list.
get_building_info(buildings, verbose = TRUE)get_building_info(buildings, verbose = TRUE)
buildings |
Integer, character, or vectors of those types, providing building id(s) or name(s). You can provide multiple buildings at once. |
verbose |
Logical. If TRUE (default), print status messages. |
A data.frame of building info with two columns, 'id' and 'name'.
Retrieve buildings that you have access to.
get_buildings(id)get_buildings(id)
id |
(Optional) An integer if you want information on a particular entity. Returns all entities unless this argument is provided. |
A data.frame of all building information.
Get all deployments in your organization.
get_deployments(org_id)get_deployments(org_id)
org_id |
organization id |
A data.frame of all deployments.
Query all equipment types from Onboard's Data Model.
get_equip_types()get_equip_types()
A data.frame containing all equipment types.
Queries equipment by their ids.
get_equipment_by_ids(id)get_equipment_by_ids(id)
id |
Integer or integer vector, containing one or many equipment ids. |
A data.frame of the requested equipment, or an empty list if no equipment matches those ids.
## Not run: equipment <- get_equipment_by_ids(c(1000,1001)) # If you are using the point selector function: query <- PointSelector() query$buildings <- 101 query$equipment_types <- 'ahu' selection <- select_points(query) equipment <- get_equipment_by_ids(selection$equipment) ## End(Not run)## Not run: equipment <- get_equipment_by_ids(c(1000,1001)) # If you are using the point selector function: query <- PointSelector() query$buildings <- 101 query$equipment_types <- 'ahu' selection <- select_points(query) equipment <- get_equipment_by_ids(selection$equipment) ## End(Not run)
Retrieves points and equipment for a given building or selection and outputs a clean metadata data.frame.
get_metadata(buildings, selection, verbose = TRUE)get_metadata(buildings, selection, verbose = TRUE)
buildings |
Integer, character, or vectors of those types, providing building id(s) or name(s). You can provide multiple buildings at once. |
selection |
Selection list from point selector. |
verbose |
Logical. If TRUE (default), print status messages. |
A data.frame of clean metadata for the requested points.
## Not run: metadata <- get_metadata(buildings=c(427,"Laboratory")) OR query <- PointSelector() query$buildings <- 427 query$equipment_types <- 'ahu' query$point_types <- c('Supply Air Temperature','Supply Air Static Pressure') selection <- select_points(query) metadata <- get_metadata(selection) ## End(Not run)## Not run: metadata <- get_metadata(buildings=c(427,"Laboratory")) OR query <- PointSelector() query$buildings <- 427 query$equipment_types <- 'ahu' query$point_types <- c('Supply Air Temperature','Supply Air Static Pressure') selection <- select_points(query) metadata <- get_metadata(selection) ## End(Not run)
Retrieve Organizations that you have access to.
get_orgs(id)get_orgs(id)
id |
(Optional) An integer if you want information on a particular entity. Returns all entities unless this argument is provided. |
A data.frame of organization information.
Queries all point types, measurements and their units from Onboard's Data Model and returns a clean output.
get_point_types()get_point_types()
A data.frame containing all point types.
Queries data points by their ids.
get_points_by_ids(id)get_points_by_ids(id)
id |
Integer or list of integers. One or many point ids. |
A data.frame of the requested points, or an empty list if there are no points with those ids.
## Not run: points <- get_points_by_ids(c(10000,10001)) # If you are using the point selector function: query <- PointSelector() query$buildings <- 101 query$equipment_types <- 'ahu' query$point_types <- c('Supply Air Temperature','Supply Air Static Pressure') selection <- select_points(query) points <- get_points_by_ids(selection$points) ## End(Not run)## Not run: points <- get_points_by_ids(c(10000,10001)) # If you are using the point selector function: query <- PointSelector() query$buildings <- 101 query$equipment_types <- 'ahu' query$point_types <- c('Supply Air Temperature','Supply Air Static Pressure') selection <- select_points(query) points <- get_points_by_ids(selection$points) ## End(Not run)
Gets metadata from the staging area.
get_staged_data(building, verbose = TRUE)get_staged_data(building, verbose = TRUE)
building |
Character vector or integer corresponding to the building name or id. If you enter multiple building ids or names, only the first entry is considered. |
verbose |
Logical. If TRUE (default), prints status and progress messages. |
A data.frame of metadata from the staging area.
Provides clean time-series
get_timeseries(start_time, end_time, point_ids)get_timeseries(start_time, end_time, point_ids)
start_time |
Start Time in UTC. |
end_time |
End Time in UTC. |
point_ids |
Point IDs for which timeseries data needs to be queried. |
A wide data.frame of time-series data, with timestamp and all requested point IDs as columns.
Retrieves timeseries data in raw format.
get_timeseries_raw(start_time, end_time, point_ids)get_timeseries_raw(start_time, end_time, point_ids)
start_time |
Start Time in UTC. |
end_time |
End Time in UTC. |
point_ids |
Point IDs for which timeseries data needs to be queried. |
A long data.frame of time series data, with point id, timestamp, and raw point values as columns.
Retrieve all user info in your organization.
get_users(id)get_users(id)
id |
(Optional) An integer if you want information on a particular entity. Returns all entities unless this argument is provided. |
A data.frame of all user information.
A list of parameters to query metadata.
PointSelector()PointSelector()
An empty named list of possible point selection criteria.
## Not run: query <- PointSelector() query$buildings <- 101 query$equipment_types <- 'ahu' query$point_types <- c('Supply Air Temperature','Supply Air Static Pressure') ## End(Not run)## Not run: query <- PointSelector() query$buildings <- 101 query$equipment_types <- 'ahu' query$point_types <- c('Supply Air Temperature','Supply Air Static Pressure') ## End(Not run)
Promote valid data on the staging area to the live building.
promote_staged_data(building, data_to_promote, verbose = TRUE)promote_staged_data(building, data_to_promote, verbose = TRUE)
building |
Character vector or integer corresponding to the building name or id. If you enter multiple building ids or names, only the first entry is considered. |
data_to_promote |
(Optional) If missing, all valid topics are promoted. A data.frame containing columns 'e.equip_id' & 'p.topic'. |
verbose |
Logical. If TRUE (default), prints status and progress messages. |
A named list containing any errors that may have occured during data promotion.
Returns a list of ids based on the input query from PointSelector. Uses http POST call to query data.
select_points(query)select_points(query)
query |
query supplied from PointSelector. |
A named list of all the points requested by the query.
## Not run: query <- PointSelector() query$buildings <- 427 query$equipment_types <- 'ahu' query$point_types <- c('Supply Air Temperature','Supply Air Static Pressure') selection <- select_points(query) ## End(Not run)## Not run: query <- PointSelector() query$buildings <- 427 query$equipment_types <- 'ahu' query$point_types <- c('Supply Air Temperature','Supply Air Static Pressure') selection <- select_points(query) ## End(Not run)
Uploads data to the staging area.
upload_staging(building, data_to_upload, skip_topics = FALSE, verbose = TRUE)upload_staging(building, data_to_upload, skip_topics = FALSE, verbose = TRUE)
building |
Character vector or integer corresponding to the building name or id. If you enter multiple building ids or names, only the first entry is considered. |
data_to_upload |
A data.frame to upload to the staging area. Must contain e.equip_id and p.topic columns. |
skip_topics |
Logical. If True, the uploaded topics will be assigned '__SKIP__' equip_id. |
verbose |
Logical. If TRUE (default), prints status and progress messages. |
A named list containing any errors that may have occured during data upload.