.. currentmodule:: logging
.. _logging:

Module Logging
==============

The OMC-045 datalog format is used by a variety of Observator products including OMC-Data-Online. This page documents the API to log data using the OMC-045 Datalog Format. 
It is not explain the datalog format itself. See the Logger Data Format document for more information about the format itself.


Constructor
-----------

.. class:: logging.DataLog045(system_id)

   Create a OMC045 datalog format object which can be used to log data to a file.

     - ``system_id`` is the name of the system/product

     - ``substation`` is the name of the substation, which is important when multiple dataloggers are used in the same system/product

Methods
-------
.. method:: DataLog045.add_sensor(name, unit, tag) -> SensorField

   Add a sensor to the header of the file. A new sensor can't be added logging is started(start function is called).

   - ``name`` The name of the sensor. Is not allowed to contain ``\`` and ``;``.
   - ``unit`` The data unit in which the data is logged. Is not allowed to contain ``\`` and ``;``.
   - ``tag`` The tag of the sensor, also known as the parameter code, which is an abbreviation of the name. This should be unique and is not allowed to contain ``\``, ``;`` or spaces.

.. method:: DataLog045.start() -> bool

   Create a file with the current time in the name and start logging.

   Return: True if the file is succesfully created and logging can be started. False if file couldn't be created.

.. method:: DataLog045.stop()

   Stop logging to the file and close the file currently in use. The logging can be stopped and started again to create a new file with the current timestamp and resume logging.

.. method:: DataLog045.add_record(sensor: SensorField, value: number, time: datetimetuple)

   Add a data record to the file associated to the sensor. When multiple records are received within a second they are logged on the same line.

   - ``sensor`` The SensorField associated to this data record.
   - ``value`` The data to record, can be a integer or a float.
   - ``RTC`` The datetimetuple.

.. method:: DataLog045.sync()

   Synchronise the file by writing all the data in the buffer to the file.


Example
-------

The following code shows an example that logs the internal parameters to a log file, creating a new log file after logging 300 samples. ::

    import logging
    import obs
    import omc048
    from omc048 import RTC    

    log = logging.DataLog045("SYSTEM")
    temp = log.add_sensor_field('Temperature', 'C', 'TPT1')
    hum = log.add_sensor_field('Humidity', 'rh', 'HUM')
    bat = log.add_sensor_field('Coin cell voltage', 'Volt', 'VBAT')
    board = omc048.onboard_sensors()
    time = RTC().datetime()
    log.start()
    index = 0

    while True:
        index += 1
        temperature = board.temp()
        humidity = board.hum()
        battery = board.vbat()
        log.add_record(temp, temperature, time)
        log.add_record(hum, humidity, time)
        log.add_record(bat, battery, time)
        obs.delay(1000)
        if index > 300:
            print("Starting new log")
            index = 0
            log.stop()
            log.start()