search

Anrijs / Aranet4-Python

Aranet4, Aranet2 and Aranet Radiation Python client
MIT License
212 stars 18 forks source link
aranet2 aranet4 bluetooth python

readme

Aranet4 Python client

Python library and command line interface for Aranet4, Aranet2, Aranet Radiation and Aranet Radon Plus sensors.

Installation

  1. Install aranet4 and its dependencies: 
    pip3 install aranet4
  2. Pair Aranet device
  3. Run aranetctl or use as a library

Note: "Smart Home integrations" must be enabled in the Aranet Home mobile application for full support.

aranetctl usage

$ aranetctl -h
usage: aranetctl.py [-h] [--scan] [-u URL] [-r] [-s DATE] [-e DATE] [-o FILE] [-w] [-l COUNT] [--xt] [--xh] [--xp] [--xc] [--set-interval MINUTES]
                    [--set-integrations {on,off}] [--set-range {normal,extended}]
                    [device_mac]

positional arguments:
  device_mac            Aranet Bluetooth Address

options:
  -h, --help            show this help message and exit
  --scan                Scan for Aranet devices
  -r, --records         Fetch historical log records

Options for current reading:
  -u URL, --url URL     Remote url for current value push

Filter History Log Records:
  -s DATE, --start DATE
                        Records range start (UTC time, example: 2019-09-29T14:00:00
  -e DATE, --end DATE   Records range end (UTC time, example: 2019-09-30T14:00:00
  -o FILE, --output FILE
                        Save records to a file
  -w, --wait            Wait until new data point available
  -l COUNT, --last COUNT
                        Get <COUNT> last records
  --xt                  Don't get temperature records
  --xh                  Don't get humidity records
  --xp                  Don't get pressure records
  --xc                  Don't get co2 records

Change device settings:
  --set-interval MINUTES
                        Change update interval
  --set-integrations {on,off}
                        Toggle Smart Home Integrations
  --set-range {normal,extended}
                        Change bluetooth range

Scan devices

Usage: aranetctl --scan

Output:

=======================================
  Name:     Aranet4 00001
  Address:  AA:BB:CC:DD:EE:FF
  RSSI:     -83 dBm
---------------------------------------
  CO2:            484 ppm
  Temperature:    20.9 °C
  Humidity:       43 %
  Pressure:       1024.8 hPa
  Battery:        3 %
  Status Display: GREEN
  Age:            9/60

Note: To receive current measurements directly from the Bluetooth advertisement data, "Smart Home integrations" must be enabled and device firmware version must be v1.2.0 or newer.

Current Readings Example

Usage: aranetctl XX:XX:XX:XX:XX:XX

Output:

--------------------------------------
Connected: Aranet4 00000 | v0.3.1
Updated 51 s ago. Intervals: 60 s
5040 total readings
--------------------------------------
CO2:          904 ppm
Temperature:  19.9 C
Humidity:     51 %
Pressure:     997.0 hPa
Battery:      96 %
Status Display: GREEN
--------------------------------------

Get History Example

Write full log to screen:

Usage: aranetctl XX:XX:XX:XX:XX:XX -r

-------------------------------------------------------------
Device Name    :        Aranet4 00000
Device Version :               v0.3.1
-------------------------------------------------------------
 id  |        date         |  co2   | temp | hum | pressure |
-------------------------------------------------------------
   1 | 2022-02-18T14:15:44 |    844 | 21.8 |  50 |    985.6 |
   2 | 2022-02-18T14:20:44 |    846 | 21.8 |  50 |    985.9 |
   3 | 2022-02-18T14:25:44 |    843 | 22.0 |  50 |    986.4 |
   4 | 2022-02-18T14:30:44 |    881 | 22.1 |  50 |    986.4 |
   5 | 2022-02-18T14:35:44 |    854 | 22.1 |  50 |    987.3 |
   6 | 2022-02-18T14:40:44 |    867 | 22.2 |  50 |    987.5 |
   7 | 2022-02-18T14:45:44 |    883 | 22.1 |  50 |    988.1 |
   8 | 2022-02-18T14:50:44 |    921 | 22.1 |  50 |    988.6 |
   9 | 2022-02-18T14:55:44 |    930 | 22.0 |  50 |    989.1 |
  10 | 2022-02-18T15:00:44 |    954 | 22.0 |  50 |    989.5 |
-------------------------------------------------------------

Usage: aranetctl XX:XX:XX:XX:XX:XX -r -o aranet4.csv

Output file format: Date,CO2,Temperature,Humidity,Pressure

Output file example:

date,co2,temperature,humidity,pressure
2022-02-18 10:05:47,1398,23.2,53,986.6
2022-02-18 10:10:47,1155,23.1,50,986.3

Usage of library

Current Readings Example

import aranet4

device_mac = "XX:XX:XX:XX:XX:XX"

current = aranet4.client.get_current_readings(device_mac)

print("co2 reading:", current.co2)
print("Temperature:", current.temperature)
print("Humidity:", current.humidity)
print("Pressure:", current.pressure)

Logged Readings Example

import aranet4

device_mac = "XX:XX:XX:XX:XX:XX"

history = aranet4.client.get_all_records(
    device_mac, entry_filter={"humi": False, "pres": False}
)
print(f"{'Date':^20} | {'CO2':^10} | {'Temperature':^10} ")
for entry in history.value:
    print(f"{entry.date.isoformat():^20} | {entry.co2:^10} | {entry.temperature:^10}")

Library functions

get_current_readings(mac_address: str) -> client.CurrentReading

Get current measurements from device Returns CurrentReading object:

class CurrentReading:
    name: str = ""
    version: str = ""
    temperature: float = -1
    humidity: int = -1
    pressure: float = -1
    co2: int = -1
    battery: int = -1
    status: int = -1
    interval: int = -1
    ago: int = -1
    stored: int = -1

get_all_records(mac_address: str, entry_filter: dict) -> client.Record

Get stored datapoints from device. Apply any filters if required

entry_filter is a dictionary that can have the following values:

Returns CurrentReading object:

class Record:
    name: str
    version: str
    records_on_device: int
    filter: Filter
    value: List[RecordItem] = field(default_factory=list)

Which includes these objects:

class RecordItem:
    date: datetime
    temperature: float
    humidity: int
    pressure: float
    co2: int

class Filter:
    begin: int
    end: int
    incl_temperature: bool
    incl_humidity: bool
    incl_pressure: bool
    incl_co2: bool