.. module:: ncv7240

**************
NCV7240 Module
**************

.. _datasheet: https://www.onsemi.com/pub/Collateral/NCV7240-D.PDF

This module contains the Zerynth driver for the OnSemi NCV7240 automotive 
eight channel low-side/relay driver, that can be controlled with a standard SPI
interface or parallel input pins.

Each output driver is protected for over load current and includes an
output clamp for inductive loads. Open load or shorts to ground can be detected
when the driver is in the off state.

    
.. class:: NCV7240

    The NCV7240 class implements several methods to access the I/O expander over
    an SPI bus and easily control its features.
    
    Each one of the 8 channels can be configured in one of 4 modes:
    
        * **Standby** (default) - the channel is disabled
        * **On** - the output driver is active (low), with over-load fault detection
        * **Off** - the output driver is inactive, with open-load fault detection
        * **Input** - the output driver on/off state is controlled by input pins (PWM capable)
    
    :note: Faults are latched and must be cleared by switching the channel to Standby mode to attempt recovery.
    :note: Off mode and open-load detection can be used as way to read channels as digital inputs.
    
.. method:: __init__(spidrv, cs, clk=500000)

        Creates an instance of NCV7240 class, using the specified SPI settings.

        :param spidrv: the *SPI* driver to use (SPI0, ...)
        :param cs: Chip select pin to access the NCV7240 chip
        :param clk: Clock speed, default 500 kHz
        
        :note: SPI mode is fixed by the slave chip protocol (CPOL=0,CPHA=1)
        
.. method:: setChannel(channel, mode)

        Set one channel to the specified mode.

        :param channel: Index of the channel (0-7) 
        :param mode: One of the four possible modes: ``CH_STANDBY``, ``CH_ON``, ``CH_OFF``, ``CH_INPUT``
        
.. method:: setAllChannels(mode)

        Set all channels to the specified mode.

        :param mode: One of the four possible modes: ``CH_STANDBY``, ``CH_ON``, ``CH_OFF``, ``CH_INPUT``
        
        :note: If *mode* is a list or a tuple, each element specifies the corresponding channel mode
        
.. method:: getChannel(channel)

        Get the status of the specified channel.

        :param channel: Index of the channel (0-7) 
        
        :returns: One of the two possible states: ``CH_OPEN``, ``CH_FAULT``

        :note: Put the channel in Standby mode to clear status.
        
.. method:: getAllChannels()

        Get the status of all channels.

        :returns: A tuple where each element specifies the corresponding channel state: ``CH_OPEN`` or ``CH_FAULT``

        :note: Put the channel in Standby mode to clear status.
        
.. method:: channelInputMode(channel)

        Set the specified channel to input mode (output driver state is controlled directly by the corresponding input pin on the NCV7240 chip).

        :param channel: Index of the channel (0-7) 
        
.. method:: channelStandby(channel)

        Set the specified channel to standby mode (output driver and fault detection are disabled, fault status cleared).

        :param channel: Index of the channel (0-7) 
        
.. method:: channelOn(channel)

        Switch the specified channel output driver on (polarity active-low, over-load/over-temperature fault detection is active).

        :param channel: Index of the channel (0-7) 
        
.. method:: channelOff(channel)

        Switch the specified channel output driver off (open-load fault detection current is active).

        :param channel: Index of the channel (0-7) 
        
.. method:: isChannelOpen(channel)

        Returns whether the channel status indicates an open-load fault (only meaningful when the channel is off).

        :param channel: Index of the channel (0-7) 

        :note: Put the channel in Standby mode to clear fault status.
        
.. method:: isChannelFault(channel)

        Returns whether the channel status indicates an over-current/over-temperature fault (only meaningful when the channel is on).

        :param channel: Index of the channel (0-7) 

        :note: Put the channel in Standby mode to clear fault status.