# Introduction to cumulocityr

    library(cumulocityr)
    library(knitr)

### Introduction

This vignette introduces the main functions with a few examples.

### Authentication

Credentials and base url for cumulocity are stored in a user’s private `.Renviron` file.

The credentials are defined as follows:

    CUMULOCITY_base_url = "[tenant url]"
    CUMULOCITY_usr = "[username]"
    CUMULOCITY_pwd = "[password]"
    CUMULOCITY_device_id = "[an example device id]"

The tenant url should be of the form “https://tenant_name.cumulocity.com”. `CUMULOCITY_device_id` is provided for convenience, but is not required by any of the main functions.

The file `.Renviron` can be edited with `usethis::edit_r_environ()`.

### Get devices

Get devices for the tenant and display a few columns. If no arguments are passed, `get_devices()` returns all devices.

    devices <- get_devices()
    print(devices[,c("type", "name", "id")])
    #>              type           name    id
    #> 1 c8y_SensorPhone     Pixel 2 XL  1200
    #> 2        c8y_Demo  A demo device   200
    #> 3            <NA>     DemoDevice 51868
    #> 4  c8y_MQTTDevice Temperature #1 53700

### Get measurements

Get measurements for device “Temperature #1” and plot the result. Datetimes are returned as character strings; we first convert to `POSIXct` before plotting.

    meas <- get_measurements(device_id = 53700,
                             num_rows = 100,
                             date_from = "2019-09-30T19:59:00Z")
    kable(head(meas[c("time", "type", "c8y_Temperature.T.value")]))

time | type | c8y_Temperature.T.value
--- | --- | ---
2019-09-30T19:59:00.850Z | c8y_Temperature | 2.079117
2019-09-30T19:59:05.851Z | c8y_Temperature | 9.135455
2019-09-30T19:59:10.850Z | c8y_Temperature | 8.090170
2019-09-30T19:59:15.851Z | c8y_Temperature | 6.691306
2019-09-30T19:59:20.853Z | c8y_Temperature | 5.000000
2019-09-30T19:59:25.851Z | c8y_Temperature | 3.090170

    time_parsed <- as.POSIXct(meas$time, format = "%Y-%m-%dT%H:%M:%OSZ", tz = "Z")

    plot(time_parsed, meas$c8y_Temperature.T.value, type = "l",
         xlab = "Time", ylab = "Temperature (deg C)")

### Get events

Similarly, we can get events for the same device:

    events <- get_events(device_id = 53700,
                         num_rows = 6,
                         date_from = "2019-09-30T19:59:00Z")

    kable(events[c("type", "time", "c8y_Position.lng", "c8y_Position.alt")])

type | time | c8y_Position.lng | c8y_Position.alt
--- | --- | --- | ---
c8y_LocationUpdate | 2019-10-01T04:53:57.435Z | 77 | 88
c8y_LocationUpdate | 2019-10-01T04:53:52.435Z | 33 | 44
c8y_LocationUpdate | 2019-10-01T04:53:47.434Z | 22 | 33
3 | 2019-10-01T04:53:42.432Z | NA | NA
c8y_LocationUpdate | 2019-10-01T04:51:27.419Z | 77 | 88
c8y_LocationUpdate | 2019-10-01T04:51:22.418Z | 33 | 44

### Unparsed data

By default, the content is parsed, but it is possible to return a list of JSON objects.

    meas_03 <- get_measurements(device_id = 53700,
                                num_rows = 2,
                                date_from = "2019-09-30T19:59:00Z",
                                parse_json = FALSE)

    print(meas_03)
    #> [[1]]
    #> [1] "{\"next\":\"https://mg.cumulocity.com/measurement/measurements?dateTo=2019-10-16T15:31:16Z&pageSize=2&source=53700&dateFrom=2019-09-30T19:59:00Z&currentPage=2\",\"self\":\"https://mg.cumulocity.com/measurement/measurements?dateTo=2019-10-16T15:31:16Z&pageSize=2&source=53700&dateFrom=2019-09-30T19:59:00Z&currentPage=1\",\"statistics\":{\"totalPages\":null,\"currentPage\":1,\"pageSize\":2},\"measurements\":[{\"self\":\"https://mg.cumulocity.com/measurement/measurements/53701\",\"time\":\"2019-09-30T19:59:00.850Z\",\"id\":\"53701\",\"source\":{\"self\":\"https://mg.cumulocity.com/inventory/managedObjects/53700\",\"id\":\"53700\"},\"type\":\"c8y_Temperature\",\"c8y_Temperature\":{\"T\":{\"unit\":\"\\u00baC\",\"value\":2.0791169082}}},{\"self\":\"https://mg.cumulocity.com/measurement/measurements/53702\",\"time\":\"2019-09-30T19:59:05.851Z\",\"id\":\"53702\",\"source\":{\"self\":\"https://mg.cumulocity.com/inventory/managedObjects/53700\",\"id\":\"53700\"},\"type\":\"c8y_Temperature\",\"c8y_Temperature\":{\"T\":{\"unit\":\"\\u00baC\",\"value\":9.1354545764}}}]}"