Type: Package
Title: 'Arduino Iot Cloud API' R Client
Version: 0.1.0
Maintainer: Flavio Leccese <flavioleccese92@gmail.com>
Description: Easily interact with the 'Arduino Iot Cloud API' https://www.arduino.cc/reference/en/iot/api/, managing devices, things, properties and data.
License: MIT + file LICENSE
Encoding: UTF-8
URL: https://flavioleccese92.github.io/Rduinoiot/
BugReports: https://github.com/FlavioLeccese92/Rduinoiot/issues/
Language: en-US
RoxygenNote: 7.1.2
Imports: httr, jsonlite, tibble, cli, purrr, methods
Suggests: knitr, rmarkdown, dplyr
VignetteBuilder: knitr
NeedsCompilation: no
Packaged: 2022-09-13 14:38:14 UTC; fleccese
Author: Flavio Leccese [aut, cre]
Repository: CRAN
Date/Publication: 2022-09-14 06:00:11 UTC

Create Auth Token for Arduino IoT Cloud API

Description

Obtain an authorization token using your personal client_id and client_secret.

Official documentation: API Summary

Usage

create_auth_token(
  client_id = Sys.getenv("ARDUINO_API_CLIENT_ID"),
  client_secret = Sys.getenv("ARDUINO_API_CLIENT_SECRET"),
  store_token = "option",
  return_token = FALSE,
  silent = FALSE,
  ...
)

Arguments

client_id

Your client id (default is the environmental variable ARDUINO_API_CLIENT_ID)

client_secret

Your client secret (default is the environmental variable ARDUINO_API_CLIENT_SECRET)

store_token

Where your token is stored. If option it will be saved into the .Rprofile (not cross-session), if envir it will be saved as an environmental variable.

return_token

If TRUE returns the token value as output of the function.

silent

Whether to hide or show API method success messages (default FALSE)

...

Additional parameters needed for the body of the POST request:

  • token_url (default: ⁠https://api2.arduino.cc/iot/v1/clients/token/⁠)

  • grant_type (default: client_credentials)

  • audience (default: ⁠https://api2.arduino.cc/iot/⁠)

  • content_type (default: application/x-www-form-urlencoded)

Value

A token valid for Arduino IoT Cloud API. It can retrievable by getOption('ARDUINO_API_TOKEN') (if store_content = "option") or by Sys.getenv("ARDUINO_API_TOKEN") (if store_token = "envir")

Examples

## Not run: 
# Sys.setenv(ARDUINO_API_CLIENT_ID = 'INSERT CLIENT_ID HERE')
# Sys.setenv(ARDUINO_API_CLIENT_SECRET = 'INSERT CLIENT_SECRET HERE')

create_auth_token()

## End(Not run)

Devices API methods

Description

List and show devices, events, properties associated to the user

Official documentation:

Usage

devices_list(
  serial = NULL,
  tags = NULL,
  store_token = "option",
  token = NULL,
  silent = FALSE
)

devices_show(device_id, store_token = "option", token = NULL, silent = FALSE)

devices_get_events(
  device_id,
  limit = NULL,
  start = NULL,
  store_token = "option",
  token = NULL,
  silent = FALSE
)

devices_get_properties(
  device_id,
  show_deleted = FALSE,
  store_token = "option",
  token = NULL,
  silent = FALSE
)

Arguments

serial

serial number of the device you may want to filter from the list (not device_id)

tags

tags you may want to filter from the list

store_token

Where your token is stored. If option it will be retrieved from the .Rprofile (not cross-session and default), if envir it will be retrieved from environmental variables list (cross-session)

token

A valid token created with create_auth_token or manually. It not NULL it has higher priority then store_token

silent

Whether to hide or show API method success messages (default FALSE)

device_id

The id of the device (The arn of the associated device)

limit

The number of events to select

start

A Posixct or Date object. Time at which to start selecting events

show_deleted

If TRUE, shows the soft deleted properties. Default to FALSE

Value

A tibble showing extensive information about devices (and related things) associated to the user

Examples

## Not run: 
library(dplyr)
Sys.setenv(ARDUINO_API_CLIENT_ID = 'INSERT CLIENT_ID HERE')
Sys.setenv(ARDUINO_API_CLIENT_SECRET = 'INSERT CLIENT_SECRET HERE')

create_auth_token()

### check properties list ###
d_list = devices_list()
device_id = d_list %>% slice(1) %>% pull(id)

devices_show(device_id = device_id)

### get device events ###
devices_get_events(device_id = device_id)

### get device properties ###
devices_get_properties(device_id = device_id)


## End(Not run)

Properties (of devices) API methods

Description

List properties associated to a given device

Usage

devices_properties_list(
  device_id,
  show_deleted = FALSE,
  store_token = "option",
  token = NULL,
  silent = FALSE
)

Arguments

device_id

The id of the device

show_deleted

If TRUE, shows the soft deleted properties. Default to FALSE

store_token

Where your token is stored. If option it will be retrieved from the .Rprofile (not cross-session and default), if envir it will be retrieved from environmental variables list (cross-session)

token

A valid token created with create_auth_token or manually. It not NULL it has higher priority then store_token

silent

Whether to hide or show API method success messages (default FALSE)

Details

Official documentation: devicesV2GetProperties

Value

A tibble showing the information about properties for given device.

Examples

## Not run: 
library(dplyr)

Sys.setenv(ARDUINO_API_CLIENT_ID = 'INSERT CLIENT_ID HERE')
Sys.setenv(ARDUINO_API_CLIENT_SECRET = 'INSERT CLIENT_SECRET HERE')
create_auth_token()

device_id = "fa7ee291-8dc8-4713-92c7-9027969e4aa1"

### check properties list ###
devices_properties_list(device_id = device_id)

## End(Not run)

Data start Properties (of devices) API methods

Description

[Experimental]

Get device properties values in a range of time (note: this API method is bugged and waiting to be fixed by Arduino team. Here for completeness and future developments but would not suggest using it)

Official documentation: devicesV2Timeseries

Usage

devices_properties_timeseries(
  device_id,
  property_id,
  start = NULL,
  limit = NULL,
  store_token = "option",
  token = NULL,
  silent = FALSE
)

Arguments

device_id

The id of the device

property_id

The id of the property

start

A Posixct or Date object. The time at which to start selecting properties.

limit

The number of properties to select

store_token

Where your token is stored. If option it will be retrieved from the .Rprofile (not cross-session and default), if envir it will be retrieved from environmental variables list (cross-session).

token

A valid token created with create_auth_token or manually. It not NULL it has higher priority then store_token

silent

Whether to hide or show API method success messages (default FALSE)

Value

A tibble showing of time and value for property of given device

Examples

## Not run: 
Sys.setenv(ARDUINO_API_CLIENT_ID = 'INSERT CLIENT_ID HERE')
Sys.setenv(ARDUINO_API_CLIENT_SECRET = 'INSERT CLIENT_SECRET HERE')
create_auth_token()

device_id = "fa7ee291-8dc8-4713-92c7-9027969e4aa1"
property_id = "d1134fe1-6519-49f1-afd8-7fe9e891e778"

devices_properties_timeseries(device_id = device_id, property_id = property_id,
 start = "2022-08-20", limit = 10)

## End(Not run)

Tags (of devices) API methods

Description

Upsert (create/update), List and Delete tags associated to a given device

Official documentation:

Usage

devices_tags_upsert(
  device_id,
  key,
  value,
  store_token = "option",
  token = NULL,
  silent = FALSE
)

devices_tags_list(
  device_id,
  store_token = "option",
  token = NULL,
  silent = FALSE
)

devices_tags_delete(
  device_id,
  key,
  store_token = "option",
  token = NULL,
  silent = FALSE
)

Arguments

device_id

The id of the device

key

The key of the tag (no spaces allowed)

value

The value of the tag (no spaces allowed)

store_token

Where your token is stored. If option it will be retrieved from the .Rprofile (not cross-session and default), if envir it will be retrieved from environmental variables list (cross-session).

token

A valid token created with create_auth_token or manually. It not NULL it has higher priority then store_token.

silent

Whether to hide or show API method success messages (default FALSE)

Value

A tibble showing information about chosen tag or list of tags for given device

Examples

## Not run: 
Sys.setenv(ARDUINO_API_CLIENT_ID = 'INSERT CLIENT_ID HERE')
Sys.setenv(ARDUINO_API_CLIENT_SECRET = 'INSERT CLIENT_SECRET HERE')
create_auth_token()

device_id = "fa7ee291-8dc8-4713-92c7-9027969e4aa1"
### create/modify tag ###
devices_tags_upsert(device_id = device_id, key = "1", value = "test")

### check tags list ###
devices_tags_list(device_id = device_id)

### delete tag ###
devices_tags_delete(device_id = device_id, key = "1")

## End(Not run)

Batch queries API methods

Description

[Experimental]

Returns the batch of time-series data or last data point for a property of given thing (note: this API method is bugged and waiting to be fixed by Arduino team. Here for completeness and future developments but would not suggest using it)

Official documentation:

Usage

series_batch_query(
  from,
  to,
  interval = NULL,
  Q,
  SeriesLimit = NULL,
  store_token = "option",
  token = NULL,
  silent = FALSE
)

series_batch_query_raw(
  from,
  to,
  interval = NULL,
  Q,
  SeriesLimit = NULL,
  store_token = "option",
  token = NULL,
  silent = FALSE
)

series_batch_last_value(
  thing_id,
  property_id,
  store_token = "option",
  token = NULL,
  silent = FALSE
)

Arguments

from

A Posixct or Date object. Get data with a timestamp >= to this value

to

A Posixct or Date object. Get data with a timestamp < to this value

interval

(numeric) Resolutions in seconds (seems not to affect results)

Q

The query. (Not clear what this means but allows to chose among properties by filling in, for instance, ⁠property.fbf34284-91f0-42be-bbf6-dd46cfb3f1e0⁠)

SeriesLimit

Maximum number of values (seems not to affect results)

store_token

Where your token is stored. If option it will be retrieved from the .Rprofile (not cross-session and default), if envir it will be retrieved from environmental variables list (cross-session)

token

A valid token created with create_auth_token or manually. It not NULL it has higher priority then store_token

silent

Whether to hide or show API method success messages (default FALSE)

thing_id

The id of the thing

property_id

The id of the property

Value

A tibble showing of time and value for properties

Examples

## Not run: 
Sys.setenv(ARDUINO_API_CLIENT_ID = 'INSERT CLIENT_ID HERE')
Sys.setenv(ARDUINO_API_CLIENT_SECRET = 'INSERT CLIENT_SECRET HERE')

create_auth_token()

### series_batch_query ###
series_batch_query(from = "2022-08-15", to = "2022-08-22",
Q = "property.fbf34284-91f0-42be-bbf6-dd46cfb3f1e0")

### series_batch_query_raw ###
series_batch_query_raw(from = "2022-08-15", to = "2022-08-22",
Q = "property.fbf34284-91f0-42be-bbf6-dd46cfb3f1e0")

### series_batch_last_value ###
thing_id = "b6822400-2f35-4d93-b3e7-be919bdc5eba"
property_id = "fbf34284-91f0-42be-bbf6-dd46cfb3f1e0"

series_batch_last_value(thing_id = thing_id, property_id = property_id)

## End(Not run)

Things API methods

Description

Create, Update, List, Show and Delete properties associated to a given thing

Official documentation:

Usage

things_create(
  device_id = NULL,
  thing_id = NULL,
  name = NULL,
  properties = NULL,
  timezone = NULL,
  force = FALSE,
  store_token = "option",
  token = NULL,
  silent = FALSE
)

things_update(
  device_id = NULL,
  thing_id = NULL,
  name = NULL,
  properties = NULL,
  timezone = NULL,
  force = FALSE,
  store_token = "option",
  token = NULL,
  silent = FALSE
)

things_list(
  device_id = NULL,
  thing_id = NULL,
  show_deleted = FALSE,
  show_properties = FALSE,
  tags = NULL,
  store_token = "option",
  token = NULL,
  silent = FALSE
)

things_show(
  thing_id,
  show_deleted = FALSE,
  store_token = "option",
  token = NULL,
  silent = FALSE
)

things_delete(
  thing_id,
  force = FALSE,
  store_token = "option",
  token = NULL,
  silent = FALSE
)

Arguments

device_id

The id of the device (The arn of the associated device)

thing_id

The id of the thing

name

The friendly name of the thing

properties

A tibble with the following columns (see things_properties_create)

  • name (required) The friendly name of the property

  • permission (required) The permission of the property (READ_ONLY or READ_WRITE allowed)

  • type (required) The type of the property (see details for exhaustive list of values)

  • update_strategy (required) The update strategy for the property value (ON_CHANGE or TIMED allowed)

  • max_value (optional, numeric) Maximum value of this property

  • min_value (optional, numeric) Minimum value of this property

  • persist (optional, logic) If TRUE, data will persist into a timeseries database

  • tag (optional, numeric) The integer id of the property

  • update_parameter (optional, numeric) The update frequency in seconds, or the amount of the property has to change in order to trigger an update

  • variable_name (character) The sketch variable name of the property

timezone

A time zone name. Check get_timezone for a list of valid names. (default: America/New_York)

force

(logical) If TRUE, detach device from the other thing, and attach to this thing. In case of deletion, if TRUE, hard delete the thing. Default to FALSE

store_token

Where your token is stored. If option it will be retrieved from the .Rprofile (not cross-session and default), if envir it will be retrieved from environmental variables list (cross-session)

token

A valid token created with create_auth_token or manually. It not NULL it has higher priority then store_token.

silent

Whether to hide or show API method success messages (default FALSE)

show_deleted

(logical) If TRUE, shows the soft deleted things. Default to FALSE

show_properties

(logical) If TRUE, returns things with their properties, and last values. Default to FALSE

tags

tags you may want to filter from the list

Value

A tibble showing information about chosen thing or list of thing for current user

Examples

## Not run: 
library(dplyr)

# Sys.setenv(ARDUINO_API_CLIENT_ID = 'INSERT CLIENT_ID HERE')
# Sys.setenv(ARDUINO_API_CLIENT_SECRET = 'INSERT CLIENT_SECRET HERE')
create_auth_token()

### create thing ###
things_create(name = "test")

### check things list ###
t_list = things_list(silent = TRUE)
thing_id = t_list %>% filter(name == "test") %>% pull(id)

things_show(thing_id = thing_id)

### update thing ###
properties = tibble(name = c("test1", "test2"),
permission = rep("READ_ONLY", 2), type = rep("FLOAT", 2),
update_strategy = rep("ON_CHANGE", 2), update_parameter = rep(10, 2))

things_update(thing_id = thing_id, name = "test_update", properties = properties)

### delete thing ###
things_delete(thing_id = thing_id)

## End(Not run)

Properties (of things) API methods

Description

Create, Update, List, Show and Delete properties associated to a given thing

Official documentation:

Usage

things_properties_create(
  thing_id,
  name,
  permission,
  type,
  update_strategy,
  ...,
  store_token = "option",
  token = NULL,
  silent = FALSE
)

things_properties_update(
  thing_id,
  property_id,
  name,
  permission,
  type,
  update_strategy,
  ...,
  store_token = "option",
  token = NULL,
  silent = FALSE
)

things_properties_list(
  thing_id,
  show_deleted = FALSE,
  store_token = "option",
  token = NULL,
  silent = FALSE
)

things_properties_show(
  thing_id,
  property_id,
  store_token = "option",
  token = NULL,
  silent = FALSE
)

things_properties_delete(
  thing_id,
  property_id,
  store_token = "option",
  token = NULL,
  silent = FALSE
)

Arguments

thing_id

The id of the thing

name

The friendly name of the property

permission

The permission of the property (READ_ONLY or READ_WRITE allowed)

type

The type of the property (see details for exhaustive list of values)

update_strategy

The update strategy for the property value (ON_CHANGE or TIMED allowed)

...

Optional parameters for things_properties_create:

  • max_value (numeric) Maximum value of this property

  • min_value (numeric) Minimum value of this property

  • persist (logic) If TRUE, data will persist into a timeseries database

  • tag (numeric) The integer id of the property

  • update_parameter (numeric) The update frequency in seconds, or the amount of the property has to change in order to trigger an update

  • variable_name (character) The sketch variable name of the property

store_token

Where your token is stored. If option it will be retrieved from the .Rprofile (not cross-session and default), if envir it will be retrieved from environmental variables list (cross-session)

token

A valid token created with create_auth_token or manually. It not NULL it has higher priority then store_token.

silent

Whether to hide or show API method success messages (default FALSE)

property_id

The id of the property

show_deleted

If TRUE, shows the soft deleted properties. Default to FALSE

Value

A tibble showing information about chosen property or list of properties for given thing

Examples

## Not run: 
library(dplyr)

Sys.setenv(ARDUINO_API_CLIENT_ID = 'INSERT CLIENT_ID HERE')
Sys.setenv(ARDUINO_API_CLIENT_SECRET = 'INSERT CLIENT_SECRET HERE')
create_auth_token()

thing_id = "b6822400-2f35-4d93-b3e7-be919bdc5eba"

### create property ###
things_properties_create(thing_id = thing_id,
name = "test",  permission = "READ_ONLY", type = "FLOAT",
update_strategy = "ON_CHANGE", update_parameter = 10)

### check properties list ###
p_list = things_properties_list(thing_id = thing_id, show_deleted = FALSE)
property_id = p_list %>% filter(name == "test") %>% pull(id)

things_properties_show(thing_id = thing_id, property_id = property_id)

### update property ###
things_properties_update(thing_id = thing_id, property_id = property_id,
name = "test_update", permission = "READ_ONLY", type = "FLOAT",
update_strategy = "ON_CHANGE", update_parameter = 10)

### delete property ###
things_properties_delete(thing_id = thing_id, property_id = property_id)

## End(Not run)

Data from Properties (of things) API methods

Description

[Stable]

Get numerical property's historic data binned on a specified time interval (note: the total number of data points should NOT be greater than 1000 otherwise the result will be truncated)

Official documentation: propertiesV2Timeseries

Usage

things_properties_timeseries(
  thing_id,
  property_id,
  from = NULL,
  to = NULL,
  interval = NULL,
  desc = NULL,
  store_token = "option",
  token = NULL,
  silent = FALSE
)

Arguments

thing_id

The id of the thing

property_id

The id of the property

from

A Posixct or Date object. Get data with a timestamp >= to this value (default: 2 weeks ago, min: 1842-01-01, max: 2242-01-01)

to

A Posixct or Date object. Get data with a timestamp < to this value (default: now, min: 1842-01-01, max: 2242-01-01)

interval

(numeric) Binning interval in seconds (default: the smallest possible value compatibly with the limit of 1000 data points in the response)

desc

(logic) Whether data ordering (by time) should be descending. Default TO FALSE

store_token

Where your token is stored. If option it will be retrieved from the .Rprofile (not cross-session and default), if envir it will be retrieved from environmental variables list (cross-session)

token

A valid token created with create_auth_token or manually. It not NULL it has higher priority then store_token

silent

Whether to hide or show API method success messages (default FALSE)

Value

A tibble showing of time and value for property of given device

Examples

## Not run: 
# Sys.setenv(ARDUINO_API_CLIENT_ID = 'INSERT CLIENT_ID HERE')
# Sys.setenv(ARDUINO_API_CLIENT_SECRET = 'INSERT CLIENT_SECRET HERE')
create_auth_token()

thing_id = "b6822400-2f35-4d93-b3e7-be919bdc5eba"
property_id = "d1134fe1-6519-49f1-afd8-7fe9e891e778"

things_properties_timeseries(thing_id = thing_id, property_id = property_id,
desc = FALSE, interval = 60, from = "2022-08-20")

## End(Not run)

Tags (of things) API methods

Description

Upsert (create/update), List and Delete tags associated to a given thing

Official documentation:

Usage

things_tags_upsert(
  thing_id,
  key,
  value,
  store_token = "option",
  token = NULL,
  silent = FALSE
)

things_tags_list(
  thing_id,
  store_token = "option",
  token = NULL,
  silent = FALSE
)

things_tags_delete(
  thing_id,
  key,
  store_token = "option",
  token = NULL,
  silent = FALSE
)

Arguments

thing_id

The id of the thing

key

The key of the tag (no spaces allowed)

value

The value of the tag (no spaces allowed)

store_token

Where your token is stored. If option it will be retrieved from the .Rprofile (not cross-session and default), if envir it will be retrieved from environmental variables list (cross-session)

token

A valid token created with create_auth_token or manually. It not NULL it has higher priority then store_token

silent

Whether to hide or show API method success messages (default FALSE)

Value

A tibble showing information about chosen tag or list of tags for given thing

Examples

## Not run: 
# Sys.setenv(ARDUINO_API_CLIENT_ID = 'INSERT CLIENT_ID HERE')
# Sys.setenv(ARDUINO_API_CLIENT_SECRET = 'INSERT CLIENT_SECRET HERE')
create_auth_token()

thing_id = "b6822400-2f35-4d93-b3e7-be919bdc5eba"

### create/modify tag ###
things_tags_upsert(thing_id = thing_id, key = "1", value = "test")

### check tags list ###
things_tags_list(thing_id = thing_id)

### delete tag ###
things_tags_delete(thing_id = thing_id, key = "1")

## End(Not run)