Metadata-Version: 1.0
Name: python-mystrom
Version: 0.4.0
Summary: Python API for interacting with myStrom devices
Home-page: https://github.com/fabaff/python-mystrom
Author: Fabian Affolter
Author-email: fabian@affolter-engineering.ch
License: MIT
Description-Content-Type: UNKNOWN
Description: python-mystrom |License| |PyPI|
        ===================================
        
        Python API for interacting with `myStrom <https://mystrom.ch>`_ devices.
        
        Requirements
        ------------
        You need to have `Python <https://www.python.org>`_ installed.
        
        - `myStrom <https://mystrom.ch>`_ device (bulb, plug or button)
        - `requests <http://docs.python-requests.org/en/master/>`_
        - Network connection
        - Devices connected to your network
        
        Installation
        ------------
        The package is available in the `Python Package Index <https://pypi.python.org/>`_ .
        
        .. code:: bash
        
            $ pip install python-mystrom
        
        Plug/switch
        -----------
        At the moment the following endpoints are covered:
        
        - ``/report``: for getting the current state and the power consumption
        - ``/relay``: for setting the relay state
        
        You will still be able to use your device with the smartphone application,
        ``curl`` or other tools. The samples below shows how to use the switch with
        ``httpie`` and ``curl`` along with ``python-mystrom``.
        
        .. code:: bash
        
            $ http http://IP_ADDRESS_PLUG/report
            HTTP/1.1 200 OK
            Content-Length: 39
            Content-Type: application/json
            Date: Mon, 15 Feb 2016 17:52:21 GMT
        
            {
                "power": 51.630947,
                "relay": true
            }
        
        .. code:: bash
        
            $ curl -X GET http://IP_ADDRESS_PLUG/relay?state=1
        
        
        Bulb
        ----
        If the bulb is on then you should be able to retrieve the current state of
        the bulb.
        
        Browse to http://IP_ADDRESS_BULB/api/v1/device/MAC_ADDRESS_BULB or use a
        command-line tool.
        
        .. code:: bash
        
            $ curl -d "color=0;0;100" -d "action=on" http://IP_ADDRESS_BULB/api/v1/device/MAC_ADDRESS_BULB
            {
        	"5DFF7FAHZ987": 	{
        		"on": true,
        		"color": "0;0;100",
        		"mode": "hsv",
        		"ramp": 100,
        		"notifyurl": ""
        	    }
            }
        
        The bulbs are not able to handle payload formatted as JSON. It's required to
        use ``application/x-www-form-urlencoded``. Keep that in mind if something is
        not working, especially around setting the color with HSV.
        
        Set State
        `````````
        You can set the state with a POST request and a payload.
        
        - **on**: ``curl -d "action=on" http://IP_ADDRESS_BULB/api/v1/device/MAC_ADDRESS_BULB``
        - **off**:  ``curl -d "action=off" http://IP_ADDRESS_BULB/api/v1/device/MAC_ADDRESS_BULB``
        - **toggle**: ``$ curl -d "action=toggle" http://IP_ADDRESS_BULB/api/v1/device/MAC_ADDRESS_BULB``
        
        Set Color RGB
        `````````````
        One of the supported modes for setting the color is **RBG**.
        
        - **white**: ``$ curl -d "color=FF000000" http://IP_ADDRESS_BULB/api/v1/device/MAC_ADDRESS_BULB``
        - **red**: ``$ curl -d "color=00FF0000" http://IP_ADDRESS_BULB/api/v1/device/MAC_ADDRESS_BULB``
        - **green**: ``$ curl -d "color=0000FF00" http://IP_ADDRESS_BULB/api/v1/device/MAC_ADDRESS_BULB``
        - **blue**: ``$ curl -d "color=000000FF" http://IP_ADDRESS_BULB/api/v1/device/MAC_ADDRESS_BULB``
        
        Set Color HSV (Hue, Saturation, Value)
        ``````````````````````````````````````
        It's also possible to use **HSV**.
        
        .. code:: bash
        
            $ curl -d "color=0;0;100" http://IP_ADDRESS_BULB/api/v1/device/MAC_ADDRESS_BULB
        
        While "color=" is composed with hue, saturation, and value.
        
        Set Mono (white)
        ````````````````
        If you only want to set the "white" color of the bulb, use **mono**.
        
        .. code:: bash
        
            $ curl -d "color=10;100" http://IP_ADDRESS_BULB/api/v1/device/MAC_ADDRESS_BULB
        
        "color=" contains the value for the color temperature (from 1 to 18) and the
        brightness (from 0 to 100).
        
        Dimming (ramp)
        ``````````````
        Add **ramp** and an interval to set up the transition time while changing
        colors.
        
        .. code:: bash
        
            $ curl -d "action=on&ramp=1000&color=00FF0000" http://IP_ADDRESS_BULB/api/v1/device/MAC_ADDRESS_BULB
        
        The unit of measurement for ramp is milliseconds (ms).
        
        Button
        ------
        The buttons can be set with the myStrom app or directly via HTTP requests.
        
        To set the configuration the payload must contains the relevant details for
        the actions:
        
        ``$ curl -v -d "single=<url>&double=<url>&long=<url>&touch=<url>" http://IP_ADDRESS_BUTTON/api/v1/device/MAC_ADDRESS_BUTTON``
        
        Available actions:
        
        - **single**: Short push (approx. 1/2 seconds)
        - **double**: 2x sequential short pushes (within 2 seconds)
        - **long**: Long push (approx. 2 seconds)
        - **touch**: Touch of the button's surface (only affective for the WiFi
          Button +)
        
        The button is set up to extend the life span of the battery as much as
        possible. This means that only within the first 3 minutes or when connected
        to an USB port/USB charger and the battery is not full, the button is able
        to receive configuration information or publish its details.
        
        ``mystrom`` helper tool
        -----------------------
        The command-line tool ``mystrom`` can help to set up the buttons and get the
        details from bulbs and plugs.
        
        .. code:: bash
        
           $ mystrom
           Usage: mystrom [OPTIONS] COMMAND [ARGS]...
        
             Simple command-line tool to get and set the values of a myStrom devices.
        
             This tool can set the targets of a myStrom button for the different
             available actions single, double, long and touch.
        
           Options:
             --version  Show the version and exit.
             --help     Show this message and exit.
        
           Commands:
             bulb    Get and set details of a myStrom bulb.
             button  Get and set details of a myStrom button.
             config  Get and set the configuration of a myStrom...
        
        
        The examples shows how to get the details of a given bulb.
        
        .. code:: bash
        
           $ mystrom config read
           IP address of the myStrom device: IP_ADDRESS_BULB
           MAC address of the device: MAC_ADDRESS_BULB
           Read configuration from IP_ADDRESS_BULB
           {
              'MAC_ADDRESS_BULB':{
                 'type':'rgblamp',
                 'battery':False,
                 'reachable':True,
                 'meshroot':False,
                 'on':True,
                 'color':'191;90;14',
                 'mode':'hsv',
                 'ramp':100,
                 'power':0.953,
                 'fw_version':'2.25'
              }
           }
        
        Example usage of the module
        ---------------------------
        The sample below shows how to use this Python module.
        
        .. code:: python
        
            import pymystrom
        
            plug = pymystrom.MyStromPlug('IP_ADDRESS_PLUG')
        
            # Preserve state
            STATE_ON = plug.get_relay_state()
        
            # Switch relay on if the plug is currently off
            if not STATE_ON:
                print("Relay will be switched on")
                plug.set_relay_on()
                # Wait a few seconds to get a reading of the power consumption
                print("Waiting for a couple of seconds...")
                time.sleep(10)
        
            # Get the new state of the switch
            print("Relay state:", plug.get_relay_state())
            print("Power consumption:", plug.get_consumption())
        
            # Switch relay off if it was off.
            if not STATE_ON:
                plug.set_relay_off()
        
        Examples for the bulb can be found in the directory ``examples``.
        
        License
        -------
        ``python-mystrom`` is licensed under MIT, for more details check LICENSE.
        
        .. |License| image:: https://img.shields.io/badge/License-MIT-green.svg
           :target: https://pypi.python.org/pypi/python-mystrom
           :alt: License
        
        .. |PyPI| image:: https://img.shields.io/pypi/v/python-mystrom.svg
           :target: https://pypi.python.org/pypi/python-mystrom
           :alt: PyPI release
        
Platform: UNKNOWN
