README.md

# Tehama Wireless API Elixir Client

`tehama_client_ex` is an elixir client library for interacting with the [Tehama Wireless](https://www.tehamawireless.com/) API.

You can view the API documentation [here](./docs/API%20for%20Daily%20Report%20Data%202022.pdf).

[![Build Status](https://github.com/My-Utility-Billing/tehama_client_ex/actions/workflows/ci.yml/badge.svg?branch=update-api-v3)](https://github.com/My-Utility-Billing/tehama_client_ex/actions/workflows/ci.yml/badge.svg?branch=update-api-v3)
[![Module Version](https://img.shields.io/hexpm/v/tehama_client_ex.svg)](https://hex.pm/packages/tehama_client_ex)
[![Hex Docs](https://img.shields.io/badge/hex-docs-lightgreen.svg)](https://hexdocs.pm/tehama_client_ex/)
[![Total Download](https://img.shields.io/hexpm/dt/tehama_client_ex.svg)](https://hex.pm/packages/tehama_client_ex)
[![License](https://img.shields.io/hexpm/l/tehama_client_ex.svg)](https://github.com/My-Utility-Billing/tehama_client_ex/blob/main/LICENSE)
[![Last Updated](https://img.shields.io/github/last-commit/My-Utility-Billing/tehama_client_ex.svg)](https://github.com/My-Utility-Billing/tehama_client_ex/commits/main)

## Documentation

[HEX docs](https://hexdocs.pm/tehama_client_ex/TehamaClient.html) for this repository.

## Installation

If [available in Hex](https://hex.pm/docs/publish), the package can be installed
by adding `tehama_client_ex` to your list of dependencies in `mix.exs`:

```elixir
def deps do
  [
    {:tehama_client_ex, "~> 0.6.0"}
  ]
end
```

## Usage

### Authenticate

Basic usage is to authenticate to get a token...

```elixir
# on success auth will be %TehamaClient.Auth{token: "usertoken...."}
auth = TehamaClient.auth!("username", "password")
```

### Sites

Then you can get a list of **[Site](./lib/tehama_client/objects/site.ex)** objects...

```elixir
# on success sites will be a list of %TehamaClient.Site{}
sites = TehamaClient.site_list(auth)
```

### Devices

And finally using a site, you can get a list of **[Device](./lib/tehama_client/objects/device.ex)** objects...

```elixir
# on success sites will be a list of %TehamaClient.Device{}
readings = TehamaClient.report_data(auth, List.first(sites))
```

### Readings

Using a device you can get a list of device **[Reading](./lib/tehama_client/objects/reading.ex)** objects...

```elixir
# readings will be a list of %TehamaClient.Reading{}
%TehamaClient.Device{readings: readings} = List.first(readings)
```

## Examples

This repository comes with some examples. The examples require some environment variables to be set.

To run an example, go to the repository and run these command line commands:

- [Site List](./examples/site_list.ex): `mix run examples/site_list.ex` - This will authenticate and print a list of sites.
- [Basic Data](./examples/data.ex): `mix run examples/data.ex` - This will authenticate and print data for a given site.

## Change Log

### Version 0.6.0

- Add `link_quality` to Device
- Makes `Device.link_quality` an integer
- Makes `Device.battery_v` an integer
- Makes `Device.radio_dec_id` an integer
- Makes `Reading.reading` an integer
- Makes `Reading.factor` a float
- Makes `Reading.initial_meter_read` an integer

### Version 0.5.0

- Trims `name` of `TehamaClient.Site`
- Trims `apt` and `addr` of `TehamaClient.Device`

### Version 0.4.0

- Updates return response types

### Version 0.3.0

- Adds handling of `Requested item wasn't found!` error from API.

### Version 0.2.0

- Adds `TehamaClient.units/2` method.
- Adds `%TehamaClient.Unit{}` and `%TehamaClient.Meter{}` types