package net.heartshield.sensors;

import java.util.List;

/**
 * Generic interface for time series signal capture from a hardware sensor.
 *
 * @author David Madl (git@abanbytes.eu)
 * @date 2016-03-21
 */
public interface ISensor {
    /**
     * Nominal number of sample values per second.
     * Only valid after the first state transition to RUNNING. See {@link ISensor#start}
     */
    double getFps();

    /**
     * Start measurement, resetting sensor data.
     * This call is asynchronous/lightweight and may return before the sensor has started capture.
     */
    void start();

    /**
     * Stop measurement, keeping sensor data.
     * This call is blocking and only returns after the sensor is stopped.
     */
    void stop();

    /**
     * Time series of each dimension: e.g. {{t1, t2, ...}, {x1, x2, ...}}
     * Deep copies are returned. Time is seconds in {@link System#nanoTime} timebase.
     *
     * @return sensor samples recorded since {@link ISensor#start} was called
     */
    List<double[]> getSamples();

    /** @return number of samples */
    int length();

    enum State {
        STOPPED,
        STARTING, // internal transition state, not exposed via onState()
        RUNNING,
        STOPPING, // internal transition state, not exposed via onState()
        FAILED
    }

    interface Listener {
        /**
         * one or more samples were added
         * @param offset start index offset
         */
        void onData(int offset, int length);

        /** state change occurred */
        void onState(State newState);
    }

    /** events are delivered to the main thread, but pixel handling occurs in a separate thread */
    void setListener(Listener listener);

    /** obtain details after FAILED state */
    Exception getError();
}
