From 2bf706635773aec7fec555dd579e089546bee113 Mon Sep 17 00:00:00 2001 From: Eugene Triguba Date: Thu, 16 Jul 2020 11:13:48 -0500 Subject: Update readme for package changes --- README.rst | 29 +++++++++++++---------------- 1 file changed, 13 insertions(+), 16 deletions(-) (limited to 'README.rst') diff --git a/README.rst b/README.rst index 79e5965..8151a9c 100644 --- a/README.rst +++ b/README.rst @@ -65,30 +65,27 @@ Using the Lirc Package print(response.command) >>> 'VERSION' - print(response.success) - >>> True print(response.data) >>> ['0.10.1'] To get started with the package, we import ``Lirc`` and can initialize it with the defaults by passing it no arguments. -This will assume a socket path of ``/var/run/lirc/lircd``. -Furthermore, this will also then assume a socket connection -using ``AF_UNIX`` and ``SOCK_STREAM``. These are both the defaults -that should work on a Linux system. There are ports of LIRC -to Windows and macOS but using the package there is far less -common. However, both of these are configurable through options -passed to ``Lirc`` to allow it to be used on those operating systems -as well. +The defaults for ``address`` and ``socket`` are determined +by the operating system you are using and are the defaults +for LIRC on whatever platform you are on. However, they are +configurable if needed. LIRC was created for Linux, but there +are ports for macOS (through macports) and Windows (WinLIRC). -After sending any command to the LIRC daemon, this package will create -a ``LircResponse`` for us that it returns. That response contains the -command we sent to LIRC, whether it was successful, and any data that -was returned back to us. +After sending any command to the LIRC daemon, this package will +create a ``LircResponse`` for us that it returns. That response +contains the command we sent to LIRC and any data that was +returned back to us. If the command was not succesful, a +``LircCommandFailureError`` exception will be thrown. Further Documentation --------------------- -More information on how to setup the system installed LIRC, how to use this python library, -and a full API specification can be found at https://lirc.readthedocs.io/ +More information on how to setup the system installed LIRC, how to use +this python library, and a full API specification can be found at +https://lirc.readthedocs.io/ -- cgit v1.2.3 From 0b396a043753a50819dd216796617e2c5bdd386e Mon Sep 17 00:00:00 2001 From: Eugene Triguba Date: Fri, 24 Jul 2020 14:24:45 -0500 Subject: Expand on Usage section in readme --- README.rst | 27 +++++++++++++++++++++++---- 1 file changed, 23 insertions(+), 4 deletions(-) (limited to 'README.rst') diff --git a/README.rst b/README.rst index 8151a9c..b854982 100644 --- a/README.rst +++ b/README.rst @@ -30,8 +30,9 @@ LIRC Python Package :alt: License This is a python package that allows you to interact with the daemon in the -`Linux Infrared Remote Control `_ package. Interacting with -the daemon allows you to send IR signals from a computer. +`Linux Infrared Remote Control `_ package. By interacting +with the daemon, it allows you to programmatically send IR signals from a +computer. More information on the lircd daemon, socket interface, reply packet format, etc. can be found at https://www.lirc.org/html/lircd.html @@ -53,8 +54,11 @@ system as well. More information on that can be found in the `installation `_ portion of the documentation. -Using the Lirc Package ----------------------- +Usage Quick Start +----------------- + +Running a basic command +^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: python @@ -76,6 +80,7 @@ by the operating system you are using and are the defaults for LIRC on whatever platform you are on. However, they are configurable if needed. LIRC was created for Linux, but there are ports for macOS (through macports) and Windows (WinLIRC). +This package is compatible with those ports as well. After sending any command to the LIRC daemon, this package will create a ``LircResponse`` for us that it returns. That response @@ -83,6 +88,20 @@ contains the command we sent to LIRC and any data that was returned back to us. If the command was not succesful, a ``LircCommandFailureError`` exception will be thrown. +Sending IR +^^^^^^^^^^ + +.. code-block:: python + + from lirc import Lirc + + lirc = Lirc() + response = lirc.send_once("my-remote-name-in-lircd.conf.d-folder", "KEY_POWER") + + +Handling Errors +^^^^^^^^^^^^^^^ + Further Documentation --------------------- -- cgit v1.2.3 From b42076485a871470c46e3ca1a7bd27cf2f69cfc4 Mon Sep 17 00:00:00 2001 From: Eugene Triguba Date: Sun, 26 Jul 2020 18:10:19 -0500 Subject: Update usage section for package changes --- README.rst | 80 ++++++++++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 55 insertions(+), 25 deletions(-) (limited to 'README.rst') diff --git a/README.rst b/README.rst index b854982..71d164c 100644 --- a/README.rst +++ b/README.rst @@ -57,51 +57,81 @@ portion of the documentation. Usage Quick Start ----------------- -Running a basic command -^^^^^^^^^^^^^^^^^^^^^^^ +Customizing the Client +^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: python - from lirc import Lirc + import lirc - lirc = Lirc() - response = lirc.version() + client = lirc.Client() - print(response.command) - >>> 'VERSION' - print(response.data) - >>> ['0.10.1'] + print(client.version()) + >>> '0.10.1' -To get started with the package, we import ``Lirc`` and can -initialize it with the defaults by passing it no arguments. +To use this package, we instantiate a ``Client``. When we initialize +the ``Client`` in the example above, we use the defaults by passing +it no arguments. -The defaults for ``address`` and ``socket`` are determined -by the operating system you are using and are the defaults -for LIRC on whatever platform you are on. However, they are -configurable if needed. LIRC was created for Linux, but there -are ports for macOS (through macports) and Windows (WinLIRC). -This package is compatible with those ports as well. +The defaults use the ``LircdConnection`` class. These defaults depend +on your operating system and can be looked up in the full documentation. +However, we can customize these defaults if desired. -After sending any command to the LIRC daemon, this package will -create a ``LircResponse`` for us that it returns. That response -contains the command we sent to LIRC and any data that was -returned back to us. If the command was not succesful, a -``LircCommandFailureError`` exception will be thrown. +.. code-block:: python + + import socket + import lirc + + client = lirc.Client( + connection=lirc.LircdConnection( + address="/var/run/lirc/lircd", + socket=socket.socket(socket.AF_UNIX, socket.SOCK_STREAM), + timeout = 5.0 + ) + ) + +The address specifies how to reach the lircd daemon. On Windows, we pass +a (hostname, port) tuple since we connect over TCP. However on Linux and +macOS, we pass in the socket path. For the client in the example above, we +set it up using the defaults for a Linux machine. While it illustrates what +is customizable, it is not a practical example since you could just call +``Client()`` then if you're on Linux and achieve the same outcome. Sending IR ^^^^^^^^^^ .. code-block:: python - from lirc import Lirc + import lirc + + client = lirc.Client() + client.send("my-remote-name", "KEY_POWER") + client.send("my-remote-name", "KEY_3", repeat_count=2) - lirc = Lirc() - response = lirc.send_once("my-remote-name-in-lircd.conf.d-folder", "KEY_POWER") +With sending IR, we can use the `send` method and optionally, +send multiple by using the `repeat_count` keyword argument. Handling Errors ^^^^^^^^^^^^^^^ +.. code-block:: python + + import lirc + + client = lirc.Client() + + try: + client.send('some-remote', 'key_power') + except lirc.LircdCommandFailureError as error: + print('The command we sent failed! Check the error message') + print(error) + +If the command was not successful, a ``LircdCommandFailureError`` exception will be thrown. +There are other errors that may be raised, which can be looked up in the full documentation, +but this is the most likely when sending commands. + + Further Documentation --------------------- -- cgit v1.2.3 From 8a065b00d4614b041834e2d0883f4f545eab92a0 Mon Sep 17 00:00:00 2001 From: Eugene Triguba Date: Sun, 26 Jul 2020 18:51:15 -0500 Subject: Reword usage paragraph --- README.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) (limited to 'README.rst') diff --git a/README.rst b/README.rst index 71d164c..d1a65c1 100644 --- a/README.rst +++ b/README.rst @@ -91,11 +91,11 @@ However, we can customize these defaults if desired. ) The address specifies how to reach the lircd daemon. On Windows, we pass -a (hostname, port) tuple since we connect over TCP. However on Linux and -macOS, we pass in the socket path. For the client in the example above, we -set it up using the defaults for a Linux machine. While it illustrates what -is customizable, it is not a practical example since you could just call -``Client()`` then if you're on Linux and achieve the same outcome. +a ``(hostname, port)`` tuple since we connect over TCP. However on Linux and +macOS, we pass in the socket path as a string. For the client in the example +above, we set it up using the defaults for a Linux machine. While it illustrates +what is customizable, it is not a practical example since you could just call +``Client()`` if you're on Linux and achieve the same outcome. Sending IR ^^^^^^^^^^ -- cgit v1.2.3 From 2bd1163a2354c4743af895a17002d04e23b7718c Mon Sep 17 00:00:00 2001 From: Eugene Triguba Date: Sun, 13 Dec 2020 21:27:05 -0600 Subject: Clarify readme --- README.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'README.rst') diff --git a/README.rst b/README.rst index d1a65c1..a9b4be9 100644 --- a/README.rst +++ b/README.rst @@ -32,7 +32,8 @@ LIRC Python Package This is a python package that allows you to interact with the daemon in the `Linux Infrared Remote Control `_ package. By interacting with the daemon, it allows you to programmatically send IR signals from a -computer. +computer. This package is for emitting IR signals, but it does not support +listening to IR codes. More information on the lircd daemon, socket interface, reply packet format, etc. can be found at https://www.lirc.org/html/lircd.html -- cgit v1.2.3