HTTPS SSH
# Basic info #
This is a simple C library for reading data from AM2315 humdity/temperature
sensor on linux. It uses standard i2c dev interface (/dev/i2c-0) to talk to the
device. So it should work on any linux distribution.

# Understand the hardware #
This library is just a simple interface for the sensor. There are some conditions 
which needs to be met when using the library. Othewise bad
things can happen. And there is probably no simple way arround. Sampling
time of the sensor is two seconds  So you could have library call which takes
couple of seconds to complete or overengineered multithreaded solution.
Both ways seems wrong to me so you have to ensure in your application
the conditions are met.

## Standby mode ##
Sensor uses standby mode to save power and to provide more accurate
results. So it needs to be woken up before reading. The library do this
for you.

## Measuring takes time ##
It takes two seconds to take the values. It does not make any effect
to read the sensor in shorter interval then two seconds. You can even get
some garbage data if you do it more frequently.

## Measuring after reading ##
This can be surprising. The sensor measures values when it goes into
standby mode. So you always gets data from the moment when the sensor
went to sleep for the last time.
This can be a problem if you read the data in longer intervals.

If this is the case and you need up-to-date values you need read couple
of times in short interval to get curent values ant then go to sleep for
longer period. Two consequitive reads should be sufficient but according
to datasheet. However I needed three reads to get the current  values. The
result of the first two is discarded and the third one is taken as actual value.

But don't forget to wait two seconds or do something else
between readings.

# Install #
To install the library use standard make and make install. This will install
the library and simple tool am2315-get which can be used to read the sensor
from shell scripts.

# How to use it #
If you have it installed on your system all you need is add include to your project.

```
#!c
#include <am2315.h>
```

And then pass the flag -lam2315 to the linker when compiling.


```
#!c
gcc -lam2315 myapp.c -o myapp
```

In scripting languages you can use am2315-get command which prints
the temperature and humidity to standrat output.

```
#!sh

$ am2315-get /dev/i2c-1
19.6 65.3
```

# Library functions #
Theare is only a few calls to use. All functions return AM2315_SUCCESS
(which is equal to zero) or one of the error codes explained below.


```
#!c
int am2315_init(struct am2315 *sensor, const char *device);
```

- first argument is a pointer to the am2315 structure which holds the
state of the library and the second is path to the i2c device (/dev/i2c-1)
for example

- function initialize the structure wakes up the sensor and tries to read
some data to verify it's alive

- it returns AM2315_INVAL_DEVICE if device argument does not seem to be
valid i2c device, AM2315_INIT_FAILED if sensor is not responding
or AM2315_IO_ERROR if it could not write or read the i2c bus

```
#!c
int am2315_read_temp(struct am2315 *sensor, float *temp);
int am2315_read_humidity(struct am2315 *sensor, float *humidity);
int am2315_read_all(struct am2315 *sensor, float *temp, float *humidity);
```

- these functions can be used to read the values from the sensor
first argument is the am2315 structure and othres are pointers where
to store the results

- you don't have to call am2315_wakeup before because it's called
internally in these functions

- these can return AM2315_IO_ERROR if it could not write or read the bus
or AM2315_CRC_FAILED in the sensor responed but crc check of the response
failed

- the results are actually stored only if the function returns
AM2315_SUCCESS

# Examples #

You need to read values in 30s intervals and you don't care you are getting
values from the past each time you read.

```
#!c

struct am2315 am;
float temp, humidity;

if (am2315_setup(&am, argv[1]))
  exit(EXIT_FAILURE);

do {
  am2315_read_all(&am, &temp, &humidity);
  printf("%.1f %.1f\n", temp, humidity);

  sleep(30);
} while (1);
```

And if you need current value in say 10 minutes intervals.

```
#!c
struct am2315 am;
float temp, humidity;

if (am2315_setup(&am, argv[1]))
  exit(EXIT_FAILURE);

do {
  am2315_read_all(&am, &temp, &humidity))
  sleep(2);
  am2315_read_all(&am, &temp, &humidity);
  sleep(2);

  am2315_read_all(&am, &temp, &humidity);
  printf("%.1f %.1f\n", temp, humidity);

  sleep(600);
} while (1);

```