API¶

`vpf_730`¶

class vpf_730.LoggerConfig(local_db: str, serial_port: str, log_interval: int)[source]¶

A class representing the configuration of logger.

Parameters:

local_db (str) – path to the local sqlite database, where the measurements are stored
serial_port (str) – serial port that the VPF-730 sensor is connected to
log_interval (int) – the log interval in minutes (between 0 and 30)

classmethod from_argparse(args)[source]¶

Constructs a new LoggerConfig() from an argparse.Namespace(), created by the argument parser returned by vpf_730.main.build_parser().

Parameters:: args (argparse.Namespace) – arguments returned from the argument parser created by vpf_730.main.build_parser()
Return type:: vpf_730.logger.LoggerConfig
Returns:: a new instance of LoggerConfig() created from CLI arguments

classmethod from_env()[source]¶

Constructs a new LoggerConfig() from environment variables.

VPF730_LOCAL_DB - path to the sqlite database which is used as queue
VPF730_PORT - serial port that the VPF-730 sensor is connected to
VPF730_LOG_INTERVAL - interval used for logging e.g. 1 for every minute

Return type:: vpf_730.logger.LoggerConfig
Returns:: a new instance of LoggerConfig() created from environment variables.

classmethod from_file(path)[source]¶

Constructs a new LoggerConfig() from a provided .ini config file with this format:

[vpf_730]
local_db=local.db
serial_port=/dev/ttyS0
log_interval=1

Parameters:: path (str) – path to the .ini config file with the structure above
Return type:: vpf_730.logger.LoggerConfig
Returns:: a new instance of LoggerConfig() created from a config file

local_db: str¶: Alias for field number 0

log_interval: int¶: Alias for field number 2

serial_port: str¶: Alias for field number 1

class vpf_730.Measurement(timestamp: int, sensor_id: int, last_measurement_period: int, time_since_report: int, optical_range: float, precipitation_type_msg: str, obstruction_to_vision: str, receiver_bg_illumination: float, water_in_precip: float, temp: float, nr_precip_particles: int, transmission_eq: float, exco_less_precip_particle: float, backscatter_exco: float, self_test: str, total_exco: float)[source]¶

NamedTuple class representing a Measurement from the VPF-730 sensor. Data as defined in the manual: https://www.biral.com/wp-content/uploads/2019/07/VPF-710-730-750-Manual-102186.08E.pdf

Parameters:

timestamp (int) – Timestamp in milliseconds (UTC)
sensor_id (int) – Sensor identification number set by the user
last_measurement_period (int) – Last measurement period in seconds
time_since_report (int) – Time since this report was generated seconds
optical_range (float) – Meteorological optical range in km
precipitation_type_msg (str) – Precipitation type message (one of: PRECIP_TYPES)
obstruction_to_vision (str) – Obstruction to vision message (one of: OBSTRUCTION_TO_VISION)
receiver_bg_illumination (float) – Receiver background illumination
water_in_precip (float) – Amount of water in precipitation in last measurement period in mm
temp (float) – Temperature in °C
nr_precip_particles (int) – Number of precipitation particles detected in last measurement period
transmission_eq (float) – Transmissometer equivalent EXCO km ^-1
exco_less_precip_particle (float) – EXCO less precipitation particle component km ^-1
backscatter_exco (float) – Backscatter EXCO km ^-1
self_test (str) – Self-Test and Monitoring (see Manual section 4.2)
total_exco (float) – Total EXCO km ^-1

backscatter_exco: float¶: Alias for field number 13

csv_header(sep=',')[source]¶

Create a csv-file header containing all fields in the correct order: timestamp,sensor_id,last_measurement_period,time_since_report, optical_range,precipitation_type_msg,obstruction_to_vision, receiver_bg_illumination,water_in_precip,temp,nr_precip_particles, transmission_eq,exco_less_precip_particle,backscatter_exco, self_test,total_exco

Parameters:: sep (str) – separator to use for the csv, default: ,
Return type:: str
Returns:: a string containing the csv header

exco_less_precip_particle: float¶: Alias for field number 12

classmethod from_msg(msg, timestamp)[source]¶

Constructs a new Measurement() from the bytes read.

Parameters:

msg (bytes) – bytes representing a message read from the sensor using VPF730.measure() e.g. b'PW01,0060,0000,001.19 KM,NP ,HZ,00.06,00.0000,+020.5 C,0000,002.51,002.51,+011.10, 0000,000,OOO,002.51'
timestamp (int) – unix timestamp in UTC when the sensor was read

Return type:

vpf_730.vpf_730.Measurement

Returns:

a new instance of Measurement().

last_measurement_period: int¶: Alias for field number 2

nr_precip_particles: int¶: Alias for field number 10

obstruction_to_vision: str¶: Alias for field number 6

property obstruction_to_vision_readable: str¶

Return the obstruction to vision type message as a human readable message instead of the 2 digit abbreviation.T his is just for convenience and is using OBSTRUCTION_TO_VISION internally.

Returns:: text message containing the obstruction to vision type

optical_range: float¶: Alias for field number 4

precipitation_type_msg: str¶: Alias for field number 5

property precipitation_type_msg_readable: str¶

Return the precipitation type message as a human readable message instead of the 2 digit abbreviation. This is for convenience and is just using PRECIP_TYPES internally.

Returns:: text message containing the precipitation type

receiver_bg_illumination: float¶: Alias for field number 7

self_test: str¶: Alias for field number 14

sensor_id: int¶: Alias for field number 1

temp: float¶: Alias for field number 9

time_since_report: int¶: Alias for field number 3

timestamp: int¶: Alias for field number 0

to_csv(fname=None, sep=',')[source]¶

Convert a measurement to a csv formatted string in this format: timestamp,sensor_id,last_measurement_period,time_since_report, optical_range,precipitation_type_msg,obstruction_to_vision, receiver_bg_illumination,water_in_precip,temp,nr_precip_particles, transmission_eq,exco_less_precip_particle,backscatter_exco, self_test,total_exco.

if fname is set, write it to a file (using append mode).

Parameters:

fname (typing.Optional[str]) – optional - a filename to write the data to
sep (str) – separator to use for the csv, default: ,

Return type:

str | None

Returns:

a string containing the measurements formatted as csv or None when written to a file.

to_db(db_path)[source]¶

Insert the measurement into a sqlite database

Parameters:: db_path (str) – path to the sqlite database
Return type:: None

total_exco: float¶: Alias for field number 15

transmission_eq: float¶: Alias for field number 11

water_in_precip: float¶: Alias for field number 8

class vpf_730.SenderConfig(local_db: str, send_interval: int, get_endpoint: str, post_endpoint: str, max_req_len: int, api_key: str)[source]¶

A class representing the configuration of sender.

Parameters:

local_db (str) – path to the local sqlite database, where the measurements are stored
send_interval (int) – interval in minutes to send data to the endpoint minimum 1, maximum 30 (every 30 minutes)
max_req_len (int) – maximum number of measurements to send in one request
get_endpoint (str) – http endpoint to get the status from (latest data)
post_endpoint (str) – http endpoint where the data should be posted to
api_key (str)

api_key: str¶: Alias for field number 5

classmethod from_argparse(args)[source]¶

Constructs a new SenderConfig() from a argparse.Namespace(), created by the argument parser returned by vpf_730.main.build_parser().

Parameters:: args (argparse.Namespace) – arguments returned from the argument parser created by vpf_730.main.build_parser()
Return type:: vpf_730.sender.SenderConfig
Returns:: a new instance of SenderConfig() created from CLI arguments

classmethod from_env()[source]¶

Constructs a new LoggerConfig() from environment variables.

VPF730_LOCAL_DB - path to the sqlite database which is used to store data locally
VPF730_SEND_INTERVAL - interval in minutes to send data to the endpoint
VPF730_GET_ENDPOINT - http endpoint to get the status from (latest data)
VPF730_POST_ENDPOINT - http endpoint where the data should be posted to
VPF730_API_KEY - the API-key used to authenticate when sending the requests in

Return type:: vpf_730.sender.SenderConfig
Returns:: a new instance of SenderConfig() created from environment variables.

classmethod from_file(path)[source]¶

Constructs a new SenderConfig() from a provided .ini config file with this format:

[vpf_730]
local_db=local.db
send_interval=5
get_endpoint=https://api.example/com/vpf-730/status
post_endpoint=https://api.example/com/vpf-730/data
max_req_len=512
api_key=deadbeef

Parameters:: path (str) – path to the .ini config file with the structure above
Return type:: vpf_730.sender.SenderConfig
Returns:: a new instance of LoggerConfig() created from a config file

get_endpoint: str¶: Alias for field number 2

local_db: str¶: Alias for field number 0

max_req_len: int¶: Alias for field number 4

post_endpoint: str¶: Alias for field number 3

send_interval: int¶: Alias for field number 1

class vpf_730.VPF730(port, *, baudrate=1200, bytesize=8, parity='N', stopbits=1, timeout=3, xonxoff=False, rtscts=False, write_timeout=None, dsrdtr=False, inter_byte_timeout=None, exclusive=None, **kwargs)[source]¶

A class for interacting with the VPF-730 sensor. Please also see the pySerial documentation: https://pyserial.readthedocs.io/

Parameters:

port (str) – serial port the VPF-730 sensor is connected to
baudrate (int) – Baud rate such as 9600 or 115200 etc
bytesize (typing.Literal[5, 6, 7, 8]) – Number of data bits. Possible values 5, 6, 7, 8
parity (typing.Literal['N', 'E', 'O', 'M', 'S']) – Enable parity checking. Possible values: N, E, O, M, S
stopbits (int) – Number of stop bits. Possible values: 1, 1.5, 2
timeout (float) – Set a read timeout value in seconds
xonxoff (bool) – Enable software flow control
rtscts (bool) – Enable hardware (RTS/CTS) flow control
write_timeout (typing.Optional[float]) – Set a write timeout value in seconds
dsrdtr (bool) – Enable hardware (DSR/DTR) flow control
inter_byte_timeout (typing.Optional[float]) – Inter-character timeout, None to disable (default)
exclusive (typing.Optional[bool]) – Set exclusive access mode (POSIX only). A port cannot be opened in exclusive access mode if it is already open in exclusive access mode.
kwargs (typing.Any) – any additional keyword arguments

measure(polled_mode=True)[source]¶

Read the VPF-730 sensor using the previously configured serial interface and return a Measurement() or None, if the sensor did not return any data.

Parameters:: polled_mode (bool) – read the sensor in polled mode. The mode can be set in the sensor using the OSAMx command, where x is 0 for automatic message transmission disabled and 1 for automatic message transmission enabled (default: True).
Return type:: vpf_730.vpf_730.Measurement | None
Returns:: a new Measurement() containing the data read from the sensor

open_ser()[source]¶

Context manager for opening and closing the serial port

Return type:: collections.abc.Generator[None]

send_command(command)[source]¶

Send an ASCII command to the VPF-730. A detailed description can be found in the Biral VPF-XXX Manual starting on page 59: https://www.biral.com/wp-content/uploads/2019/07/VPF-710-730-750-Manual-102186.08E.pdf

Parameters:: command (str) – A valid command e.g: D?
Return type:: bytes
Returns:: the response of the sensor as bytest

`vpf_730.utils`¶

class vpf_730.utils.FrozenDict(d)[source]¶

Immutable, generic implementation of a frozen dictionary.

Parameters:: d (Mapping[K, V])

vpf_730.utils.connect(db_path)[source]¶

Context manager to connect to a sqlite database.

Parameters:: db_path (str) – path to the sqlite database
Return type:: collections.abc.Generator[sqlite3.Connection]
Returns:: A Generator yielding an open sqlite connection

vpf_730.utils.retry(retries, exceptions=(<class 'Exception'>, ))[source]¶

Decorator to retry a function retries times when a specific exceptions is raised (defined in exceptions). If any other exception is raised, it will not retry the function.

It can be used like this: A function is decorated and it is retried a maximum of 10 times when a ValueError or KeyError is raised. Every other exception will instantly be raised.

@retry(retries=10, exceptions=(ValueError, KeyError))
def my_func():
    ...

Parameters:

retries (int) – number of times a function is retried
exceptions (tuple[type[Exception], ...]) – the exceptions to except and retry

Return type:

typing.Callable[[typing.Callable[[typing.ParamSpec(P)], typing.TypeVar(R)]], typing.Callable[[typing.ParamSpec(P)], typing.TypeVar(R)]]

API¶

vpf_730¶

vpf_730.utils¶

`vpf_730`¶

`vpf_730.utils`¶