README.Rmd

---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
```

# sunsynkr

<!-- badges: start -->
[![R-CMD-check](https://github.com/DavidASmith/sunsynkr/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/DavidASmith/sunsynkr/actions/workflows/R-CMD-check.yaml)
<!-- badges: end -->

`sunsynkr` is an R package to help you acquire information about Sunsynk photovoltaic systems from their API. If you have a Sunsynk inverter and an account to view and manage it on [SunsynkConnect](https://sunsynk.net/), you should be able to use this package to retrieve information about your plant. 

Note that this package is unofficial and is in no way associated with Sunsynk. It may stop working (or return misleading outputs) at any time and without warning.

Also note that this package is currently at an early stage of development. Functions may not work as specified and things may change fundamentally in future versions. 

## Installation

From R, you can install the current release of `sunsynkr` like so:

``` r
devtools::install_github("DavidASmith/sunsynkr")
```

## Example usage

First, load the package.

```{r example}
library(sunsynkr)
```

### Authentication

You must configure environment variables to hold your sunsynk username and password (the ones you use to login to SunsynkConnect at https://sunsynk.net/). Configure the following environment variables:

- `SUNSYNK_USER`
- `SUNSYNK_PASS`

### Get a token

All `sunsynkr` functions which call the API require a token as an argument. Accordingly, you must first acquire an authentication token.

```{r}
token <- get_token()
token
```

You can now use this token to authenticate other `susynkr` functions to the API.

### Get plants details

```{r include=FALSE}
# Redact personal info
redact_character <- function(x) {
  gsub("\\w", "X", x)
}

redact_plants <- function(x) {
  
  plant_infos <- x$data$infos
  
  redact_plant <- function(x) {
    x$id <- redact_character(x$id)
    x$name <- redact_character(x$name)
    x$thumbUrl <- redact_character(x$thumbUrl)
    x$address <- redact_character(x$address)
    x$email <- redact_character(x$email)
    x$phone <- redact_character(x$phone)
    x$masterId <- redact_character(x$masterId)
    
    x
  }
  
  x$data$infos <- lapply(plant_infos, redact_plant)
  
  x
  
}

```

You can now get details of all plants associated with your account.

```{r}
plants <- get_plants(token)

```

```{r include=FALSE}
plant_id <- plants$data$infos[[1]]$id

plants <- plants |> 
  redact_plants()
```

Printing the `sunsynkr_plants` object returns a tibble summarising the information available for each plant.

```{r}
plants

```

### Flow

We can query the most recent power flow from the API for a given plant. We can extract the plant from `plants` like this. 

```{r eval=FALSE}
plant_id <- plants$data$infos[[1]]$id
```

Then, we can obtain the power flow for the plant.

```{r}
flow <- get_flow(token, 
                 plant_id)

```

Printing the `sunsynkr_flow` object outputs a representation of the power flows managed by the inverter.

```{r}
flow
```

### Day summary

You can return a summary of all power flows (and battery state of charge) at five minute intervals for a given day.

```{r}

date <- lubridate::today() - lubridate::days(1)

day_summary_table <- get_day_summary_table(token, 
                                           plant_id, 
                                           date)

day_summary_table
```

You can also generate a plot of the day summary table.

```{r fig.height=6, fig.width=6}
plot(day_summary_table)
```