# Testing Sensors / Features 

## Pre-requisites 
1. IoT Dev Board (Raspberry Pi 3/4 preferred)
1. microSD card and microSD card Reader/Adapter
1. Chosen Hardware Sensor 


## Pre-Testing Checklist 
Before you begin testing please, Check 

- [X] Ensure that the H/W sensor is working perfectly. 
(Test with Arduino and Arduino library to know if the sensor H/W works)
- [X] Ensure that the sensor is fully ported.
- [X] Ensure that an example for your Sensor/Feature is available in the `examples/` folder.


## Steps for Testing 

1. Install Shunya OS.
2. Install the library.
3. Compile the examples.
4. Connect Hardware.
5. Configure and Run.


### Step 1: Install Shunya OS.

Download and Install Shunya OS, follow this [guide](https://github.com/shunyaos/shunyainterfaces/wiki/Install-Shunya-OS) if you have any problems installing 
Shunya OS.

Boot into Shunya Interfaces and you are ready to test!. 

### Step 2: Install Shunya Interfaces

Shunya Interfaces uses Cmake as it build engine, you can follow these steps to 
compile and install the library from scratch.

**Note**: These steps are for native compile (i.e Run these commands on Shunya OS).
Currently, We do not have instructions for cross-compiling (i.e Compiling on your laptop) 
the library.

#### Clone Shunya Interfaces

Running these commands below on the Terminal in Shunya OS, should get you the 
latest source.

```sh
# Clone the project, Skip if you have cloned the project.
git clone https://github.com/shunyaos/shunyainterfaces.git
cd shunyainterfaces
```

#### Checkout the branch 
Most of the sensor under testing may not be available in the `master` branch,
So Checkout to the testing branch by running command.

**How to find the branch name?**: Each sensor that is under porting must have
an issue, Please check [issues](https://github.com/shunyaos/shunyainterfaces/issues) 
tab, navigate to the sensor specific issue, and you will find the branch-name.

TODO: Dry run this once, Check if this is true. Make it easy for the testers to find 
the branch and checkout. 

```sh 
git checkout <branch-name>
```

#### Configure, Build and Install 
Running these commands in the Terminal should get shunya interfaces installed.

```sh
# Create a build directory
mkdir build
cd build 
# Configure 
cmake ../
# Build 
make 
# Install Shunya Interfaces
sudo make install 
```

### Step 3: Compile Examples
You will find examples for testing the sensor in the `examples/` folder, compiling 
the example is just compiling a C program. 

```sh
# Command assumes that you are in build folder, from the previous run
# Change the cd command according to your current folder.
cd ../examples 
# Replace the names appropriately
gcc -o test example.c -lshunyaInterfaces_user -lshuynaInterfaces_core
```

### Step 4: Connect Hardware
It is time to connect sensors to the board. 

#### Checklist for Connecting

- [X] Make sure dev board power supply is off, before you start connecting.
- [X] Check the Vcc and GND pins of the sensor are connected correctly.
- [X] Check if you connected 1.8 V or 3.3 V pin on the dev board to the Sensors 
1.8V or 3.3V pin and **not the 5V pin**.

After checking these things you can connect the Power Supply to the dev Board.

**Note**:

### Step 5: Configure Shunya Interfaces and Run.

Tell Shunya Interfaces your hardware connections, by writing the connections 
into a YAML file. 

You will find the file at `/etc/shunya/interfaces/config.yaml`

to Open the file Run command 
```sh
$ sudo vi /etc/shunya/interfaces/config.yaml
```
#### What do we write into the file ?

We write Pin number to Sensor ID, key:value pairs, where pin number is the key
and Sensor ID is the value.

For Example:
```sh
pin 3: 1.1 # Key: Value
```

#### What are Sensor ID's ?

Sensors for Shunya Interfaces are represented in Sensor ID's. Sensors also 
have pins, these Pins are also numbered and these numbers are called 

Each Sensor is given a number (**Sensor ID**) which the Shunya Interfaces library recognizes. 
And *each data pins*(pins used for data transfer) on the Sensor is given a number 
(**Connection ID**).

So when we write `pin 1: 1.1` Shunya Interfaces understands it as 
`<Sensor 1>`.`<Sensor data pin 1>` connected to `pin 1` of Raspberry Pi (or a board).

For example:
Sensor 6 and Data Pin 1 connected to pin 3 on the board.
```yaml
pin 3: 6.1
```

#### Connected multiple sensors to same pin?
You can create an array of Sensor ID's and assign it to a pin.

For Example:
```yaml
pin 3: [1.1, 6.1]
```

Final Step, Just run the compiled example to test the sensor.
```sh
# Replace test with your binary name.
$ sudo ./test 
```

**Note**: Make sure to provide `sudo` permissions for the example, to make it run
correctly.