List devices

List devices

Usage

telem_read_devices(
  serial_number = NULL,
  state = NULL,
  ...,
  pages = NULL,
  dry_run = FALSE,
  verbosity = 0
)

Arguments

serial_number

Character. The collar serial.

state

Character. One of telem_device_states().

...

Further filters, passed as filter[name]=value.

pages

Optional pagination spec passed to spdgt.auth::api_get(). Defaults to NULL, which fetches every record.

dry_run

Logical. If TRUE, prints the request without sending it.

verbosity

Integer. How much to print (0 = silent, 1 = headers, 2 = headers + body, 3 = full).

Value

A tibble of devices.

Filtering

The named arguments cover the filters people reach for most. Anything else the endpoint accepts can be passed through ..., where species_id = 4 becomes filter[species_id]=4.

To find out what an endpoint accepts rather than guessing, ask it with spdgt.auth::api_discover():

spdgt.auth::api_discover("telemetry", "/individuals")

That lists every filter, include, sort and pagination option, read from the description the API publishes, so it cannot drift from what the API does.

A filter value understands a small vocabulary: "!Dead" for not equal, "?" for is-null and "!?" for is-not-null, "~elk" for a partial match, ">10" and "<10" for comparisons, and "a,b,c" for any of several values. There is no two-sided comparison — ">a,<b" does not mean between — which is why periods are given as from and to rather than as one string.

Pagination

Reads return every matching record. The API pages at 100, so a read that stopped there would silently drop the rest. Pass pages = list(size = 100) to page deliberately.

See also

spdgt.auth::api_discover() to list every filter an endpoint accepts.

Examples

if (FALSE) { # \dontrun{
telem_read_devices()
telem_read_devices(state = "Deployed")
telem_read_devices(serial_number = "103633")

# Several states at once, or everything except one.
telem_read_devices(state = "Deployed,In-Hand")
telem_read_devices(state = "!Retired")
} # }