Metadata-Version: 2.1
Name: pyvscp-sensors-bme680
Version: 0.0.6
Summary: VSCP BME680 sensor handler
Home-page: https://github.com/grodansparadis/vscp_python_sensor_bme680
Author: Ake Hedman, Grodans Paradis AB
Author-email: akhe@grodansparadis.com
License: MIT
Keywords: vscp iot m2m automation development bme680
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Build Tools
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Requires-Python: >=3.0
Description-Content-Type: text/markdown
Requires-Dist: adafruit-circuitpython-bme680
Requires-Dist: configparser
Requires-Dist: paho-mqtt
Requires-Dist: pyvscp
Requires-Dist: pyvscpclasses
Requires-Dist: pyvscphelper
Requires-Dist: pyvscptypes
Provides-Extra: dev
Requires-Dist: check-manifest ; extra == 'dev'
Provides-Extra: test
Requires-Dist: coverage ; extra == 'test'

# vscp-python-sensor-bme680

![License](https://img.shields.io/badge/license-MIT-blue.svg)

<img src="https://vscp.org/images/logo.png" width="100">

This project consisty of two scripts to deliver data from a [BME680](https://www.bosch-sensortec.com/products/environmental-sensors/gas-sensors-bme680/) sensor to a VSCP daemon (vscp-bme680.py) or a MQTT broker (mqtt-bme680.py). It is built upon the [Adafruit BME680 module](https://github.com/adafruit/Adafruit_CircuitPython_BME680)

It will deliver VSCP events for

* Temperature
* Humidity
* Pressure (raw reading)
* Pressure (adjusted for sea level)
* Altitude
* Gas concentration

Typically the scripts is used in a [cron job](https://ostechnix.com/a-beginners-guide-to-cron-jobs/) to deliver the events on timed intervals.

Adafruit is the most popular source for [BME680 breakout boards](https://www.adafruit.com/product/3660) but there are many others available also in different price ranges.

![](https://cdn-learn.adafruit.com/guides/cropped_images/000/001/822/medium640/3660_top_ORIG_2020_07.jpg?1596135784)

The scripts be configured to be used with either a SPI or I2C connected sensor.

## Install/connect the sensor

Lady Ada has written a very good tutorial on this [here](https://learn.adafruit.com/adafruit-bme680-humidity-temperature-barometic-pressure-voc-gas)

## Install

### Prerequisites

The code here is dependent on the [VSCP helper library](https://github.com/grodansparadis/vscp-helper-lib). Therefore you have to install this package first. It is available for Debian type systems including Raspberry Pi.

For convenience this is how the current version is installed on a Raaspberry Pi

```bash
wget https://github.com/grodansparadis/vscp-helper-lib/releases/download/v14.0.2/libvscphelper14_14.0.2-1_armhf.deb

wget https://github.com/grodansparadis/vscp-helper-lib/releases/download/v14.0.2/libvscphelper14-dev_14.0.2-1_armhf.deb

sudo dpkg -i ./libvscphelper14_14.0.2-1_armhf.deb
sudo dpkg -i ./libvscphelper14-dev_14.0.2-1_armhf.deb

```

Note that there may be [later versions available)(https://github.com/grodansparadis/vscp-helper-lib/releases) then the one downloaded above. You should **always** install the latest version.


### Install the package

The scripts are available as a package **vscp-python-sensor-bme680** on [PyPi](https://pypi.org/project/pyvscp-sensors-bme680/). This means you can do an automatic install with pip that will handle all dependencies expect for the helper library mentioned above which must be install manually.

The installation process is easy

```bash
pip3 install vscp-python-sensor-bme680
```

To later upgrade to the latest version use

```bash
pip3 install --upgrade vscp-python-sensor-bme680
```

It is not required but recommended to install in a virtual environment To install in a virtual environment in your current project:

```bash
mkdir project-name && cd project-name
python3 -m venv .env
source .env/bin/activate
```

then do the install of **vscp-python-sensor-bme680** as of above.

After install you can use **vscp-bme680.py** and **mqtt-bme68.py** from the command line. Info on how to configure the scripts for your needs are below.

### Manual Install

For some reason you may not want to use PyPi and want to download the scripts from the [github repository](https://github.com/grodansparadis/vscp-python-sensor-bme680).

The script depends on some other modules that you need to install before using it. It is recommended to install everything in a virtual environment.

As mentioned above you need to install the VSCP helper library before installing this module.

It is recommended to install in a virtual environment in your current project:

```bash
git clone https://github.com/grodansparadis/vscp-python-sensor-bme680.git
cd vscp-python-sensor-bme680
python3 -m venv .env
source .env/bin/activate
```

You may need to install Python venv with 

```bash
apt install python3-venv
```
if it's not installed.

#### Configparser

Configparser can be found on [PyPi](https://pypi.org/) and is documented [https://docs.python.org/3/library/configparser.html](here). Install with

```bash
pip3 install configparser
```

#### Install adafruit-circuitpython-bme680 module
On supported GNU/Linux systems like the Raspberry Pi, you can install the driver locally from PyPI. To install for current user:

```bash
pip3 install adafruit-circuitpython-bme680
```

To install system-wide (this may be required in some cases):

```bash
sudo pip3 install adafruit-circuitpython-bme680
```

#### Install VSCP modules

**pyvscphelper** is not needed if only MQTT should be used. You can install the modules from [PyPi](https://pypi.org/)

```bash
pip3 install pyvscp
pip3 install pyvscphelper
```

If you need them on more places either go for a global install or use a virtual environment and install all the modules in it.

#### Install MQTT module

For MQTT functionality Paho MQTT module is needed. You can install the modules from PyPi

```bash
pip3 install paho-mqtt
```

## Configure

You setup the code by either editing the scripts or create a configuration file with the settings. In the scripts all relevant values can be found in the beginning of the file along with documentation.

The settings are named the same in the config file as in the script itself so the documentation for the configuration file is valid also for directly adding the scripts.

To get help you can issue

```bash
vscp-bme680.py --help
```

or

```bash
mqtt-bme680.py --help
```

The recommended way to configure the scripts is to use a configuration file and store this file in a safe location as it contains usernames and password. The syntax to instruct the sctipty top read a configuration file is

```bash
xxxx-bme680.py --configure path-to-config-file
```

So 

```bash
vscp-bme680.py --configure /etc/vscp/bme680-config.ini
```

will read the configuration from _/etc/vscp/bme680-config.ini_

### Sample configuration file

If you install in a virtual environment as recommended above you will find a sample configuration file in 

>_.env/pyvscp-sensors-bme680-samp

For a standard install you find it in

>_.local/pyvscp-sensors-bme680-samp

and for a global install you can get the path by issuing

```bash
pip3 -V
```

### The GENERAL section

#### bVerbose

Set to 

> bVerbose = True

to get some info when the script is run. Set to

> bVerbose = False

to make the script silent.

### The [VSCP] section

#### host

Only relevant for the _vscp-bme680.py_ script.

Set the address and port for the VSCP daemon the script should deliver VSCP events to. The format is _server:port_

#### user

Only relevant for the _vscp-bme680.py_ script.

User name needed to login to the VSCP daemon.

#### password

Only relevant for the _vscp-bme680.py_ script.

Password needed to login to the VSCP daemon.

#### guid

The scripts use the MAC address of the machine they are run on to construct a GUID on the format

> FF:FF:FF:FF:FF:FF:FF:FE:M5:M4:M3:M2:M1:M0:id1:id0

where _M5:M4:M3:M2:M1:M0_ is the MAC address and _id1:id0_ sensor id. 

If you don't want this you can supply your own GUID here. Note that the two lowest positions also now is used for id's so normally the GUID should have zeros in these positions.

#### sensorindex_temperature

Sensor index for the temperature sensor. Default is that it is set to zero as the GUID is unique for each sensor. Set to a byte value of your choice if you need it.

#### sensorindex_humidity

Sensor index for the humidity sensor. Default is that it is set to zero as the GUID is unique for each sensor. Set to a byte value of your choice if you need it.

#### sensorindex_pressure

Sensor index for the pressure sensor. Default is that it is set to zero as the GUID is unique for each sensor. Set to a byte value of your choice if you need it.

#### sensorindex_pressure_adj

Sensor index for the adjusted sea level pressure. Default is that it is set to zero as the GUID is unique for each sensor. Set to a byte value of your choice if you need it.

#### sensorindex_gas

Sensor index for the gas concentration sensor. Default is that it is set to zero as the GUID is unique for each sensor. Set to a byte value of your choice if you need it.

#### sensorindex_altitude

Sensor index for the altitude. Default is that it is set to zero as the GUID is unique for each sensor. Set to a byte value of your choice if you need it.

#### zone

Set the zone to a value between 0-255 if you need it. Default is zero.

#### subzone

Set the subzone to a value between 0-255 if you need it. Default is zero.

#### id_temperature

Set id_temperature to a value between 0-65535 to set the id for the reported value. This is the two LSB bytes of the GUID used to report the sensor value. Default is 1.

#### id_humidity

Set id_temperature to a value between 0-65535 to set the id for the reported value. This is the two LSB bytes of the GUID used to report the sensor value. Default is 2.

#### id_pressure

Set id_temperature to a value between 0-65535 to set the id for the reported value. This is the two LSB bytes of the GUID used to report the sensor value. Default is 3.

#### id_pressure_adj

Set id_temperature to a value between 0-65535 to set the id for the reported value. This is the two LSB bytes of the GUID used to report the sensor value. Default is 4.

#### id_gas

Set id_temperature to a value between 0-65535 to set the id for the reported value. This is the two LSB bytes of the GUID used to report the sensor value. Default is 5.

#### id_altitude

Set id_temperature to a value between 0-65535 to set the id for the reported value. This is the two LSB bytes of the GUID used to report the sensor value. Default is 6.

### The [MQTT] section

### host

Only relevant for the _mqtt-bme680.py_ script.

The address for the MQTT broker which will get reported values.

### port

Only relevant for the _mqtt-bme680.py_ script.

Port on the MQTT broker.

### user

Only relevant for the _mqtt-bme680.py_ script.

Username used to login to MQTT broker.

### password

Only relevant for the _mqtt-bme680.py_ script.

Password used to login to MQTT broker.

### topic_temperature

Only relevant for the _mqtt-bme680.py_ script.

This is the topic under which the temperature event will be sent. The default is

> vscp/{xguid}/miso/{xclass}/{xtype}

- _{xguid}_ will be replaced with the GUID of the event.
- _{xclass}_ will be replaced with the VSCP class of the event.
- _{xtype}_ will be replaced with the VSCP type of the event.

**miso** stands for Master In Slave Out and is used by VSCP when talking to a MQTT broker. **mosi** is the opposite, Master Out Slave In. 

### topic_humidity

Only relevant for the _mqtt-bme680.py_ script.

This is the topic under which the humidity event will be sent. The default is

> vscp/{xguid}/miso/{xclass}/{xtype}

See __topic_temperature__ for full info.

### topic_pressure

Only relevant for the _mqtt-bme680.py_ script.

This is the topic under which the pressure event will be sent. The default is

> vscp/{xguid}/miso/{xclass}/{xtype}

See __topic_temperature__ for full info.

### topic_pressure_adj

Only relevant for the _mqtt-bme680.py_ script.

This is the topic under which the sea level adjusted pressure event will be sent. The default is

> vscp/{xguid}/miso/{xclass}/{xtype}

See __topic_temperature__ for full info.

### topic_gas

Only relevant for the _mqtt-bme680.py_ script.

This is the topic under which the gas concentration event will be sent. The default is

> vscp/{xguid}/miso/{xclass}/{xtype}

See __topic_temperature__ for full info.

### topic_altitude

Only relevant for the _mqtt-bme680.py_ script.

This is the topic under which the altitude event will be sent. The default is

> vscp/{xguid}/miso/{xclass}/{xtype}

See __topic_temperature__ for full info.

### The [BME680] section

### sea_level_pressure 

Pressure at sea level. Used for pressure adjustment. Default is 1013.25

### temp_corr

Correction value for sensor temperature reading. The value entered here will be subtracted from the reading. Default is 0. 


### height_at_location

Set the height in meters for your location. Used for pressure adjustments. Default is 412.0 meters.


----

If you are interested in learning more about VSCP the main site is [here](https://www.vscp.org)

Copyright © 2000-2020 Ake Hedman, Grodans Paradis AB - MIT license.



