<commit_before># pyMYS
It is a module to make easier communication with MySensor's network.

This module was originally based on pymysensors module. However, in its way it took some changes which led it to what 
you can see now.

You can find more information about the MySensors Project on its official webpage (http://www.mysensors.org/).

## Documentation

Currently, all documentation can be accessed in project's GitHub page.

## Dependencies

You can find all dependencies in requirements.txt and
install them using pip.

- pyserial

## Installation

    python setup.py install

or

    pip pymys

## Support

This project should support all Python 3 versions. However, it was only tested with Python 3.4.

## Protocol Version Supported

This module should support MySensors 1.4, 1.5 and 1.6 protocol.

## Data Structures

    Gateway                     Implements Gateway's base
        - nodes                 Dictionary of nodes
        - protocol_version      Gateway's protocol version
        - log_queue             A queue of log messages
        - const                 Variable that points to the module of contants (mys_14, mys_15, mys_16, ...)
        - callbacks             A dictionary that points to the functions which will handle each message type
    
    SerialGateway               It is an specialization to communicate over Serial port
    
    EthernetGateway             It is an specialization to communicate over Ethernet port
    
    Node                        Implements Node structure
        - id                    Node's id
        - sensors               Dictionary of sensors
        - sketch_name           Sketch name
        - sketch_version        Sketch version
        - battery_level         Battery level
    
    Sensor                      Implements Sensor structure
        - id                    Sensor's id
        - type                  Sensor's type
        - values                Dictionary of values
    
    Message                     Implements Message structure
        - node_id               Node's id
        - sensor_id             Sensor's id
        - type                  Message type
        - ack                   If a message is an ACK message
        - sub_type              Subtype Message
        - payload               Message's payload

## Methods

    Gateway
        - connect               Connects on the interface. It should be implemented on child classes
        - disconnect            Disconnects from the interface. It should be implemented on child classes
        - send                  Sends a message to the network. It should be implemented on child classes
        - receive               Receives a message from the network. It should be implemented on child classes
        - presentation          Handles presentation messages
        - set                   Handles set messages
        - req                   Handles request messages
        - stream                Handles stream messages
        - internal              Handles internal messages
        - process               Try to receive a message and handle it
        - get_free_id           Return a free id to be assign to a node
    
    Node
        - add_sensor            Includes a node in list of sensors
        - set_sensor_value      Set a new value to a sensor
    Message
        - copy                  Return a new Message object
        - decode                Fill the object using a raw message
        - encode                Return a raw message using object's information

## Customization

You can customize your own Gateway by creating a new class which inherit from the SerialGateway or EthernetGateway or 
even from base Gateway (you will have to implement some required methods such as connect, send and receive). After that, 
you just need to implement the methods you want to change.

    from pymys import mysensors as mys
    
    class NewSerialProtocol(mys.SerialGateway):
        def presentation(self, msg):
            # Overwriting presentation handle
            pass

If you don't want to create a whole new class, you can just create a function and change on obeject's callbacks attribute/

    from pymys import mysensors as mys
    
    def presentation(gw, msg):
        # Now you can access Gateway object and Message object
        pass
    
    gw = mys.SerialGateway("/dev/ttyACM0")
    gw.callbacks[0] = presentation

## Usage

    <commit_msg>Improved docs with examples<commit_after># pyMYS
It is a module to make easier communication with MySensor's network.

This module was originally based on pymysensors module. However, in its way it took some changes which led it to what 
you can see now.

You can find more information about the MySensors Project on its official webpage (http://www.mysensors.org/).

## Documentation

Currently, all documentation can be accessed in project's GitHub page.

## Dependencies

You can find all dependencies in requirements.txt and
install them using pip.

- pyserial

## Installation

    python setup.py install

or

    pip pymys

## Support

This project should support all Python 3 versions. However, it was only tested with Python 3.4.

## Protocol Version Supported

This module should support MySensors 1.4, 1.5 and 1.6 protocol.

## Data Structures

    Gateway                     Implements Gateway's base
        - nodes                 Dictionary of nodes
        - protocol_version      Gateway's protocol version
        - log_queue             A queue of log messages
        - const                 Variable that points to the module of contants (mys_14, mys_15, mys_16, ...)
        - callbacks             A dictionary that points to the functions which will handle each message type
    
    SerialGateway               It is an specialization to communicate over Serial port
    
    EthernetGateway             It is an specialization to communicate over Ethernet port
    
    Node                        Implements Node structure
        - id                    Node's id
        - sensors               Dictionary of sensors
        - sketch_name           Sketch name
        - sketch_version        Sketch version
        - battery_level         Battery level
    
    Sensor                      Implements Sensor structure
        - id                    Sensor's id
        - type                  Sensor's type
        - values                Dictionary of values
    
    Message                     Implements Message structure
        - node_id               Node's id
        - sensor_id             Sensor's id
        - type                  Message type
        - ack                   If a message is an ACK message
        - sub_type              Subtype Message
        - payload               Message's payload

## Methods

    Gateway
        - connect               Connects on the interface. It should be implemented on child classes
        - disconnect            Disconnects from the interface. It should be implemented on child classes
        - send                  Sends a message to the network. It should be implemented on child classes
        - receive               Receives a message from the network. It should be implemented on child classes
        - presentation          Handles presentation messages
        - set                   Handles set messages
        - req                   Handles request messages
        - stream                Handles stream messages
        - internal              Handles internal messages
        - process               Try to receive a message and handle it
        - get_free_id           Return a free id to be assign to a node
    
    Node
        - add_sensor            Includes a node in list of sensors
        - set_sensor_value      Set a new value to a sensor
    Message
        - copy                  Return a new Message object
        - decode                Fill the object using a raw message
        - encode                Return a raw message using object's information

## Customization

You can customize your own Gateway by creating a new class which inherit from the SerialGateway or EthernetGateway or 
even from base Gateway (you will have to implement some required methods such as connect, send and receive). After that, 
you just need to implement the methods you want to change.

    from pymys import mysensors as mys
    
    class NewSerialProtocol(mys.SerialGateway):
        def presentation(self, msg):
            # Overwriting presentation handler
            pass
        
        def get_free_id(self):
            # You can even overwrite the algorithm which is responsible for give a free id. Currently, it just see if 
            # there is any ID free in a range from 1 to 254 and return it.
            pass

If you don't want to create a whole new class, you can just create a function and change on obeject's callbacks attribute/

    from pymys import mysensors as mys
    
    def presentation(gw, msg):
        # Now you can access Gateway object and Message object
        pass
    
    gw = mys.SerialGateway("/dev/ttyACM0")
    gw.callbacks[0] = presentation

## Usage

If you just want to print all messages that your Gateway send to you.

    from pymys import mysensors as mys


    def show_msg(msg):
        print(msg)
    
    gw = mys.SerialGateway("/dev/ttyACM0", message_callback=show_msg)
    print("Trying to connect...")
    gw.connect()
    print("Connected!")
    
    while True:
        gw.process()

Creating an application with threads which allow you write raw messages and send to your network over your Gateway

    import threading
    
    from pymys import mysensors as mys
    
    
    def run_gateway():
        while True:
            gw.process()
    
    
    def show_msg(msg):
        print("Read: {}".format(msg))
    
    gw = mys.SerialGateway("/dev/ttyACM0", message_callback=show_msg)
    print("Trying to connect...")
    gw.connect()
    print("Connected!")
    
    t = threading.Thread(target=run_gateway)
    t.start()
    
    while True:
        data = input("")
        msg = mys.Message(data)
        gw.send(msg)
{'fraction_non_alphanumeric': 0.03902486975326846, 'fraction_numerical': 0.003931976801336872, 'mean_word_length': 1.7232334047109208, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3328171', 'n_tokens_mistral': 2459, 'n_tokens_neox': 2326, 'n_words': 1102}