.. _quickref:

Quick reference for the znzpi
=================================

Below is a quick reference for the znzpi Cam. If it is your first time working with
the znzpi Cam please consider reading the following sections first:

.. toctree::
   :maxdepth: 1

   general.rst
   tutorial/index.rst

.. image:: board_infor_a.jpg
    :alt: znzpi Cam Pinout
    :width: 700px

.. image:: board_infor_b.jpg
    :alt: znzpi Cam Pinout
    :width: 700px

.. image:: RV1106_io_v2.png
    :alt: znzpi Cam io Pinout
    :width: 700px

.. image:: lcd_gpio_v2.png
    :alt: znzpi Cam lcd Pinout
    :width: 700px

General znzpi Cams Board Control
---------------------------------

All znzpi Cams can use the `machine` module to control the camera hardware. Please refer to the
pinout image for which SPI/I2C/UART/CAN/PWM/TIMER channels are avialable on what I/O pins.

Delay and timing
^^^^^^^^^^^^^^^^

Use the :mod:`time <time>` module::

    import time

    time.sleep(1)           # sleep for 1 second
    time.sleep_ms(500)      # sleep for 500 milliseconds
    time.sleep_us(10)       # sleep for 10 microseconds
    start = time.ticks_ms() # get millisecond counter
    delta = time.ticks_diff(time.ticks_ms(), start) # compute time difference

Virtual Timers
^^^^^^^^^^^^^^

Example of usage::

    from machine import Timer

    tim0 = Timer(-1)
    tim0.init(period=5000, mode=Timer.ONE_SHOT, callback=lambda t:print(0))

    tim1 = Timer(-1)
    tim1.init(period=2000, mode=Timer.PERIODIC, callback=lambda t:print(1))

The period is in milliseconds.

Pins and GPIO
^^^^^^^^^^^^^

Use the :ref:`machine.Pin <machine.Pin>` class::

    from machine import Pin

    p0 = Pin('P0', Pin.OUT) # create output pin on GPIO0
    p0.on()                 # set pin to "on" (high) level
    p0.off()                # set pin to "off" (low) level
    p0.value(1)             # set pin to on/high

    p2 = Pin('P2', Pin.IN)  # create input pin on GPIO2
    print(p2.value())       # get value, 0 or 1

    p4 = Pin('P4', Pin.IN, Pin.PULL_UP) # enable internal pull-up resistor
    p5 = Pin('P5', Pin.OUT, value=1) # set pin high on creation

There's a higher-level abstraction :ref:`machine.Signal <machine.Signal>`
which can be used to invert a pin.  Useful for illuminating active-low LEDs
using ``on()`` or ``value(1)``.

UART (serial bus)
^^^^^^^^^^^^^^^^^

See :ref:`machine.UART <machine.UART>`. ::

    from machine import UART

    uart1 = UART(1, baudrate=115200)
    uart1.write('hello')  # write 5 bytes
    uart1.read(5)         # read up to 5 bytes

ADC (analog to digital conversion)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Use the :ref:`machine.ADC <machine.ADC>` class::

    from machine import ADC

    adc = ADC("P5")          # create ADC object on ADC pin
    adc.read_u16()              # read value, 0-65536 across voltage range 0.0v - 3.3v

The resolution of the ADC is 12 bit with 10 to 11 bit accuracy, irrespective of the
value returned by read_u16(). If you need a higher resolution or better accuracy, use
an external ADC.

Hardware SPI bus
^^^^^^^^^^^^^^^^

Hardware SPI is accessed via the
:ref:`machine.SPI <machine.SPI>` class and has the same methods as software SPI above::

    from machine import SPI, Pin

    spi = SPI(1, 10000000)
    cs_pin = Pin(6, Pin.OUT, value=1)
    cs_pin(0)
    spi.write('Hello World')
    cs_pin(1)

The keyword option cs=n can be used to enable the cs pin 0 or 1 for an automatic cs signal. The
default is cs=-1. Using cs=-1 the automatic cs signal is not created. 
In that case, cs has to be set by the script. Clearing that assignment requires a power cycle.

Notes:

1. Even if the highest reliable baud rate at the moment is about 30 Mhz,
   setting a baud rate will not always result in exactly that
   frequency, especially at high baud rates.

2. Sending at higher baud rate is possible. In the tests receiving
   worked up to 60 MHz, sending up to 90 MHz.

Hardware I2C bus
^^^^^^^^^^^^^^^^

Hardware I2C is accessed via the :ref:`machine.I2C <machine.I2C>` class and
has the same methods as software SPI above::

    from machine import I2C

    i2c = I2C(1, 400_000)
    i2c.writeto(0x76, b"Hello World")

Real time clock (RTC)
^^^^^^^^^^^^^^^^^^^^^

See :ref:`machine.RTC <machine.RTC>`::

    from machine import RTC

    rtc = RTC()
    rtc.datetime((2017, 8, 23, 1, 12, 48, 0, 0)) # set a specific date and time
    rtc.datetime() # get date and time
    rtc.now() # return date and time in CPython format.


RV1106 Based znzpi Cams General Board Control
---------------------------------------------

RV1106 based znzpi Cams can use the `pyb` module to control the camera hardware. Please note that
the `pyb` module will be deprecated. Please use the `machine` module for new code.

Delay and timing
^^^^^^^^^^^^^^^^

Use the :mod:`time <utime>` module::

    import utime

    utime.sleep(1)           # sleep for 1 second
    utime.sleep_ms(500)      # sleep for 500 milliseconds
    utime.sleep_us(10)       # sleep for 10 microseconds
    start = utime.ticks_ms() # get value of millisecond counter
    delta = utime.ticks_diff(utime.ticks_ms(), start) # compute time difference

LEDs
^^^^

See :ref:`pyb.LED <pyb.LED>`. ::

    from pyb import LED

    led = LED(1) # red led
    led.toggle()
    led.on()
    led.off()

LED Pinout:

* LED(1) -> Red RGB LED Segment
* LED(4) -> IR LEDs

Pins and GPIO
^^^^^^^^^^^^^

See :ref:`pyb.Pin <pyb.Pin>`. ::

    from pyb import Pin

    p_out = Pin('P7', Pin.OUT_PP)
    p_out.high()
    p_out.low()

    p_in = Pin('P8', Pin.IN, Pin.PULL_UP)
    p_in.value() # get value, 0 or 1

GPIO Pinout:

* Pin('P1') -> P1 (GPIO_0A3)
* Pin('P2') -> P2 (GPIO_0A4)
* Pin('P3') -> P3 (GPIO_0A5)
* Pin('P4') -> P4 (GPIO_4A6)
* Pin('P5') -> P5 (GPIO_4A0)
* Pin('P6') -> P6 (GPIO_4A1)
* Pin('P7') -> P7 (GPIO_4A5)
* Pin('P8') -> P8 (GPIO_4A6)
* Pin('P9') -> P9 (GPIO_4A0)

All pins are 5V tolerant with a 3.3V output (P6 is not 5V tolerant in ADC or DAC mode).

All pins can sink or source up to 25 mA (Up to 120 mA in total between all pins).

Servo control
^^^^^^^^^^^^^

See :ref:`pyb.Servo <pyb.Servo>`. ::

    from pyb import Servo

    s1 = Servo(1) # servo on position 1 (P7)
    s1.angle(45) # move to 45 degrees
    s1.angle(-60, 1500) # move to -60 degrees in 1500ms
    s1.speed(50) # for continuous rotation servos

Servo Pinout:

* Servo(2) -> P2 (GPIO_0A4)

External interrupts
^^^^^^^^^^^^^^^^^^^

See :ref:`pyb.ExtInt <pyb.ExtInt>`. ::

    from pyb import Pin, ExtInt

    callback = lambda e: print("intr")
    ext = ExtInt(Pin('P7'), ExtInt.IRQ_RISING, Pin.PULL_NONE, callback)

GPIO Pinout:

* Pin('P1') -> P1 (GPIO_0A3)
* Pin('P2') -> P2 (GPIO_0A4)
* Pin('P3') -> P3 (GPIO_0A5)
* Pin('P4') -> P4 (GPIO_4A6)
* Pin('P5') -> P5 (GPIO_4A0)
* Pin('P6') -> P6 (GPIO_4A1)
* Pin('P7') -> P7 (GPIO_4A5)
* Pin('P8') -> P8 (GPIO_4A6)
* Pin('P9') -> P9 (GPIO_4A0)

Timers
^^^^^^

See :ref:`pyb.Timer <pyb.Timer>`. ::

    from pyb import Timer

    tim = Timer(2, freq=1000)
    tim.counter() # get counter value
    tim.freq(0.5) # 0.5 Hz
    tim.callback(lambda t: pyb.LED(1).toggle())

* For znzpi Cam M4: TIM2, TIM3, and TIM4
* For znzpi Cam F7: TIM2, TIM3, TIM4 and TIM7 through TIM14
* For znzpi Cam H7: TIM2, TIM3, TIM4, TIM7, TIM8 and TIM12 through TIM17

PWM (pulse width modulation)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

See :ref:`pyb.Pin <pyb.Pin>` and :ref:`pyb.Timer <pyb.Timer>`. ::

    from pyb import Pin, Timer

    p = Pin('P4') # P4 has TIM2, CH3
    tim = Timer(2, freq=1000)
    ch = tim.channel(3, Timer.PWM, pin=p)
    ch.pulse_width_percent(50)

ADC (analog to digital conversion)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

See :ref:`pyb.Pin <pyb.Pin>` and :ref:`pyb.ADC <pyb.ADC>`. ::

    from pyb import Pin, ADC

    adc = ADC(Pin('P6'))
    adc.read() # read value, 0-4095

ADC Pinout:

* ADC(Pin('P10')) -> P6 (GPIO_4C1)

P6 is 3.3V tolerant in ADC mode - NOT 5V TOLERANT!

DAC (digital to analog conversion)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

See :ref:`pyb.Pin <pyb.Pin>` and :ref:`pyb.DAC <pyb.DAC>`. ::

    from pyb import Pin, DAC

    dac = DAC('P6')
    dac.write(120) # output between 0 and 255

DAC Pinout:

* DAC(Pin('P3')) -> P3 (GPIO_0A5)

P6 is 3.3V tolerant in DAC mode - NOT 5V TOLERANT!

UART (serial bus)
^^^^^^^^^^^^^^^^^

See :ref:`pyb.UART <pyb.UART>`. ::

    from pyb import UART

    uart = UART(3, 9600, timeout_char=1000)
    uart.write('hello')
    uart.read(5) # read up to 5 bytes

UART Pinout:

* UART 0 RX -> P5 (GPIO_4A0)
* UART 0 TX -> P6 (GPIO_4A1)
* UART 1 RX -> P7 (GPIO_4A5)
* UART 1 TX -> P8 (GPIO_4A6)

SPI bus
^^^^^^^

See :ref:`pyb.SPI <pyb.SPI>`. ::

    from pyb import SPI

    spi = SPI(1, SPI.MASTER, baudrate=1000000, polarity=1, phase=0)
    spi.send('hello')
    spi.recv(5) # receive 5 bytes on the bus
    spi.send_recv('hello') # send a receive 5 bytes

SPI Pinout:

* SPI 1 MOSI (Master-Out-Slave-In) -> P5 (GPIO_4A0)
* SPI 1 MISO (Master-In-Slave-Out) -> P6 (GPIO_4A1)
* SPI 1 SS   (Serial Select)       -> P7 (GPIO_4A5)
* SPI 1 SCLK (Serial Clock)        -> P8 (GPIO_4A6)

I2C bus
^^^^^^^

See :ref:`pyb.I2C <pyb.I2C>`. ::

    from pyb import I2C

    i2c = I2C(2, I2C.MASTER, baudrate=100000)
    i2c.scan() # returns list of slave addresses
    i2c.send('hello', 0x42) # send 5 bytes to slave with address 0x42
    i2c.recv(5, 0x42) # receive 5 bytes from slave
    i2c.mem_read(2, 0x42, 0x10) # read 2 bytes from slave 0x42, slave memory 0x10
    i2c.mem_write('xy', 0x42, 0x10) # write 2 bytes to slave 0x42, slave memory 0x10

I2C Pinout:

* I2C 0 SCL (Serial Clock) -> P5 (GPIO_4A0)
* I2C 0 SDA (Serial Data)  -> P6 (GPIO_4A1)
* I2C 1 SCL (Serial Clock) -> P3 (GPIO_0A5)
* I2C 1 SDA (Serial Data)  -> P4 (GPIO_0A6)
* I2C 2 SCL (Serial Clock) -> P7 (GPIO_4A5)
* I2C 2 SDA (Serial Data)  -> P8 (GPIO_4A6)