.. module:: rn2483

*************
RN2483 Module
*************

This Zerynth module currently supports over-the-air activation only to join a LoRaWAN network.
Class A LoRaWAN devices, after correctly joining a network, are able to transmit a message up to 222 bytes
and receive a response up to 230 bytes during the subsequent downlink session.
Sent messages can be confirmed (acknowledged) or unconfirmed; check your network policy to choose the proper 
transmit method (`datasheet <http://ww1.microchip.com/downloads/en/DeviceDoc/50002346A.pdf>`_,
`command reference <http://ww1.microchip.com/downloads/en/DeviceDoc/40001784B.pdf>`_,
`LoRaWAN specification <https://lora-alliance.org/sites/default/files/2018-04/lorawantm_specification_-v1.1.pdf>`_)

.. note:: **rn2483Exception** is defined.

Usage example: ::

    import streams
    from microchip.rn2483 import rn2483

    streams.serial()

    rst = D16
    # insert otaa credentials!!
    appeui = "" 
    appkey = ""
    print("joining...")

    if not rn2483.init(SERIAL1, appeui, appkey, rst):
        print("denied :(")
        raise Exception

    print("sending first message, res:")
    print(rn2483.tx_uncnf('TTN'))

    while True:
        print("ping, res:")
        print(rn2483.tx_uncnf("."))
        sleep(5000)


    
.. function:: get_hweui(ser = None, rst = None)

    Gets device EUI.
    If you need to get the EUI before joining a network, it is possible to specify:
    
    * *ser* serial port used for device-to-module communication (ex. SERIAL1)
    * *rst* module reset pin
    
    and call get_hweui() before init().

    
.. function:: get_ch_status(channel)

    Gets *channel* channel status: 'on' if enabled, 'off' otherwise.

    
.. function:: get_duty_cycle(channel, raw = False)

    Gets *channel* channel duty cycle: returned by default as a percentage.
    As a raw value passing *raw* as True.

    
.. function:: get_ar()

    Gets current automatic reply state ('on' or 'off').

    
.. function:: set_ar(state)

    Sets automatic reply to 'on' or 'off' state.
    Currently setting ar to 'on' does not have consequences on downlink session.

    
.. function:: set_retransmissions(n)

    Sets number of retransmissions to be used for an uplink confirmed packet,
    if no downlink acknoledgement is received from the server.

    
.. _config:

.. function:: config(appeui=None, appkey=None, deveui=None, pwridx='1', adr='off', rx2='3 869525000', retx=5, ar='off')

    Configures the lora module with otaa join credentials and other parameters.
    
    * *appeui*, *appkey* are needed for otaa
    * *deveui* is needed fot otaa too but if it is None, module's hardware eui will be used for activation
    * *pwridx* sets the output power
    * *adr* controls the adaptive data rate
    * *rx2* data rate and frequency used for the second Receive window
    * *retx* number of retransmissions to be used for an uplink confirmed packet
    * *ar* sets the state of the automatic reply

    
.. function:: set_config()
    
    Sets the configuration parameters 
    Configures the lora module with otaa join credentials and other parameters.
    
    * *appeui*, *appkey* are needed for otaa
    * *deveui* is needed fot otaa too but if it is None, module's hardware eui will be used for activation
    * *pwridx* sets the output power
    * *adr* controls the adaptive data rate
    * *rx2* data rate and frequency used for the second Receive window
    * *retx* number of retransmissions to be used for an uplink confirmed packet
    * *ar* sets the state of the automatic reply

    
    .. _join:
    
.. function:: join()
    
    Attempts to join the network using over-the-air activation.

    
.. function:: init(ser, appeui, appkey, rst, join_lora=True)

    Performs basic module configuration and try over-the-air activation.
    
    * *ser* is the serial port used for device-to-module communication (ex. SERIAL1)
    * *appeui*, *appkey* are needed for otaa
    * *rst* is the module reset pin
    * if *join_lora* is False the configuration and over-the-air activation attempt are skipped and the module can be configured through the :ref:`config() <config>` function and then the LoRa network can be joined calling the :ref:`join() <join>` function.
    
    
    
.. function:: tx_uncnf(data)

    Transmits an unconfirmed message.
    *data* is a string or a bytearray.

    Returns True if no data is available during downlink session,
    a tuple (True, resp_data), where *resp_data* is a bytearray, otherwise.

    
.. function:: tx_cnf(data)

    Transmits a confirmed message.
    *data* is a string or a bytearray.

    Returns True if no data is available during downlink session,
    a tuple (True, resp_data), where *resp_data* is a bytearray, otherwise.

    
.. function:: get_snr():
    
    Returns an integer between -128 and 127 representing the signal to noise ratio (SNR) for the last received packet.

    
.. function:: get_pwr():
    
    Returns an integer between -3 and 15 representing the current power level settings used in operation.