R Package User Guide

Overview

EcotopiaR is a R-based toolkit provided by Ecotopia.

It includes features to obtain user tokens, query device lists, and retrieve user Ecotopia data.

Installation

Option 1: Install with devtools

library(devtools)
install_github("druid-work/Ecotopia-SDK-R")

Option 2: Install with remotes

library(remotes)
install_github("druid-work/Ecotopia-SDK-R")

Configuration

1. Create a configuration file ecotopia.yml under your work folder and copy & paste the following content to the file.

# ecotopia.yml
domain: "domain_name" # eg. "www.ecotopiago.com"
username: "user_name" # If token is provided, username and password will be ignored.
password: "pass_word"
token: "token_string" # Token is optional.

2. Enter your username and password to obtain the user token before data query.

Alternatively, you can obtain the token using ecotopia_user_token function and fill in the token in the configuration file.

You can only access data generated by your own devices.

Functions

1. ecotopia_user_token

Get a token by login to Ecotopia.

@return a character string of the token for API calling.

@example

token <- ecotopia_user_token()

2. ecotopia_data_devices

Get User's Devices table from Ecotopia

@param max_devices Limit max count of devices returned. default is 1000.

@param start_date Require devices start from the specified time.

@return A dataframe of device information.

@example

devices <- ecotopia_data_devices(
  max_devices = 1000,
  start_date = "2019-01-01"
)

3. ecotopia_data_all_{type}

Get all given types of data from Ecotopia API

There are four types of data provided: acc, env, gps, odba

@param show_progress Show download progress log. show_progress can be "OFF", "SIMPLE" or "FULL"

@param start_time Start time of the data to be downloaded

@return List of all devices contains a list of vectors with their given types of data.

@example

data <- ecotopia_data_all_gps(
  show_progress = "SIMPLE",
  start_time = "2024-05-06 02:29:11"
)

4. ecotopia_data_devices_{type}

Get devices' given types of data from Ecotopia API

There are four types of data provided: acc, env, gps, odba

@param device_ids Device IDs to get data from

@param show_progress Show download progress log. show_progress can be "OFF", "SIMPLE" or "FULL"

@param start_time Start time of the data to be downloaded

@return List of devices contains a list of vectors with their given types of data.

@example

data <- ecotopia_data_devices_acc(
  device_uuids = c("device_uuid1", "device_uuid2", "device_uuid3"),
  show_progress = "SIMPLE",
  start_time = "2024-05-06 02:29:11"
)