diff options
| author | Eugene Triguba <eugenetriguba@gmail.com> | 2021-04-18 18:47:57 -0500 |
|---|---|---|
| committer | Eugene Triguba <eugenetriguba@gmail.com> | 2021-04-18 18:47:57 -0500 |
| commit | b400aba3f82eb7a490bdbc8d141777e82d625ac8 (patch) | |
| tree | 98ff11d0da726cefcfee455dbcffdc9a8ed23959 /docs | |
| parent | Add note to customizing client (diff) | |
| download | lirc-b400aba3f82eb7a490bdbc8d141777e82d625ac8.zip | |
Update docs
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/source/configuring-system-lirc.rst | 10 | ||||
| -rw-r--r-- | docs/source/hardware-setup.rst | 7 | ||||
| -rw-r--r-- | docs/source/installation.rst | 14 | ||||
| -rw-r--r-- | docs/source/usage.rst | 120 |
4 files changed, 114 insertions, 37 deletions
diff --git a/docs/source/configuring-system-lirc.rst b/docs/source/configuring-system-lirc.rst index 5122804..6527344 100644 --- a/docs/source/configuring-system-lirc.rst +++ b/docs/source/configuring-system-lirc.rst @@ -40,7 +40,11 @@ the remote configuration file. The RedRat3-II is now discontinued, although `its driver's are still available <https://www.redrat.co.uk/support/firmware-drivers/>`_, but you could look into the `RedRatX <https://www.redrat.co.uk/products/redrat-x/>`_ or see if you can find a `RedRat3-II used <https://www.ebay.com/sch/i.html?_nkw=redrat3-ii&_sacat=0>`_. Place this -generated remote configuration file in your ``lircd.conf.d`` folder. +generated remote configuration file in your ``/etc/lirc/lircd.conf.d`` folder. + +******************************* +Iguanaworks IR Transciever Note +******************************* If you're using an Iguanaworks IR Transciever, you may find the discussion below useful. Basically, the device should just work on the default driver. @@ -61,8 +65,8 @@ macOS ----- On macOS, the paths are almost the same as the Linux ones, just prefixed with ``/opt/local/``. -Therefore, the LIRC configuration is typically at ``/opt/local/etc/lirc/`` and the lircd socket -is at ``/opt/local/var/run/lirc/lircd`` +Therefore, the LIRC configuration is typically at ``/opt/local/etc/lirc/`` and the lircd +socket is at ``/opt/local/var/run/lirc/lircd``. Refer to the Linux section for the rest of the configuration as they are almost the same besides the ``/opt/local/`` prefix. However, on macOS, there is also no ``default`` driver like there is diff --git a/docs/source/hardware-setup.rst b/docs/source/hardware-setup.rst index 27bb489..ef3a3e4 100644 --- a/docs/source/hardware-setup.rst +++ b/docs/source/hardware-setup.rst @@ -1,5 +1,8 @@ Hardware Setup ============== -In order to use this package, you'll need to have an IR emitter -or transciever hooked up to your computer.
\ No newline at end of file +This package will work as long as you have a lirc daemon running. You can use +the ``version()`` method on the ``Client`` and see what version of the lirc +daemon is running. However, in order to do anything useful (such as sending +IR codes), you'll need to have an IR emitter or transciever hooked up to your +computer and recognized by lirc.
\ No newline at end of file diff --git a/docs/source/installation.rst b/docs/source/installation.rst index e8255de..e6eec34 100644 --- a/docs/source/installation.rst +++ b/docs/source/installation.rst @@ -34,15 +34,15 @@ Linux: Windows: - * WinLIRC at http://winlirc.sourceforge.net/ is a port for Windows. + * `WinLIRC <http://winlirc.sourceforge.net/>`_ is a port for Windows. It works a bit differently since it is just a collection of files - in a folder that you run. More information on that can be found - at `using LIRC on Windows <./using-lirc-on-windows.html>`_. + in a folder that you run. More information on setting up WinLIRC can be found + at `configuring the system LIRC <./configuring-system-lirc.html>`_. macOS: - * There is a port on MacPorts at https://ports.macports.org/port/lirc/summary - with it's source code on GitHub at https://github.com/andyvand/LIRC. However, + * There is `a port on MacPorts <https://ports.macports.org/port/lirc/summary>`_ + with it's `source code on GitHub <https://github.com/andyvand/LIRC>`_. However, it doesn't appear to be maintained any longer and is not the latest LIRC version. - You can then run ``port install lirc`` or build the package from source using - the instructions on the README of the GitHub repository.
\ No newline at end of file + You can still install it using ``port install lirc`` or build the package from + source using the instructions on the README of the GitHub repository.
\ No newline at end of file diff --git a/docs/source/usage.rst b/docs/source/usage.rst index 9b2fee9..118a307 100644 --- a/docs/source/usage.rst +++ b/docs/source/usage.rst @@ -13,26 +13,46 @@ The most relevant of these is ``Client``, since this is the main class you will be using. ``LircdConnection`` is the object that is used to configure the connection to LIRC when you initialize the ``Client``. -***************** -Initializing Lirc -***************** +If you want to catch any of the exceptions, those are all under ``lirc.exceptions``. -The ``Client`` class takes in one optional keyword argument: connection. -This connection must be a ``LircdConnection``. This connection, if not -specified manually, will have default values to connecting to lircd for -the operating system you are using. So the simplest way to construct ``Client`` -is with no arguments at all. +.. code-block:: python + + from lirc.exceptions import ( + LircError, + LircdSocketError, + LircdConnectionError, + LircdInvalidReplyPacketError, + LircdCommandFailureError, + UnsupportedOperatingSystemError + ) + +*********************** +Initializing the Client +*********************** .. code-block:: python - from lirc import Client + import lirc + + client = lirc.Client() + + print(client.version()) + >>> '0.10.1' - lirc_client = Client() +To use this package, we instantiate a ``Client``. By initializing it +with no arguments, the ``Client`` will attempt to connect to the lirc +daemon with the default connection parameters for your operating system. + +However, if you've instantiated the ``Client`` without any arguments, +you don't get any errors, and you recieve a response from the ``version()`` +command, you are connected to the daemon. Most people should not need to +change the default parameters. Overriding LIRC Defaults on Initialization ========================================== -However, if we the defaults don't work for us or we have a more complex setup? +However, what if we the defaults don't work for us or we have a more complex setup? + Let's say we're on Windows and we want to connect over TCP to a remote LIRC server on another Windows machine. So we've passed in an ``address`` to override the default so it doesn't look for the daemon on the localhost. ``socket`` and ``timeout`` are @@ -51,6 +71,23 @@ passed in just to show that we can, these are already the defaults on Windows. ) ) +The ``Client`` takes in one optional keyword argument: connection. +This connection must be a ``LircdConnection``. This connection, if not +specified manually, will have default values to connecting to lircd for +the operating system you are using. + +The ``address`` specifies how to reach the lircd daemon. On Windows, +we pass a ``(hostname, port)`` tuple since we connect over TCP such as +``('localhost', 8765)``. However on Linux and macOS, we pass in the path +to the socket on the filesystem as a string. + +The ``socket`` is the connection type. On Linux/macOS, it will default to a UNIX +domain socket connection. On Windows, ``socket.socket(socket.AF_INET, socket.SOCK_STREAM)`` +is used for a connection over TCP. + +Lastly, ``timeout`` specifies the amount of time to wait when reading from the socket +for a response. + LIRC Initialization Defaults per Operating System ================================================= @@ -69,17 +106,17 @@ is created will be the same. However if we are on Windows, we can't use unix domain sockets. Instead, WinLIRC uses TCP to communicate with the lirc daemon. So instead of a string -for the address, it defaults to a tuple of ("localhost", 8765), which is the -default on WinLIRC. The first part contains the address whereas the second is -the port. Furthermore, the socket that is created uses ``AF_INET`` and -``SOCK_STREAM`` instead so we can connect over TCP. +for the address, it defaults to a tuple of ``("localhost", 8765)``, which is the +default connection parameters for WinLIRC. The first part contains the address +whereas the second is the port. Furthermore, the socket that is created uses +``AF_INET`` and ``SOCK_STREAM`` instead so we can connect over TCP. **************** Sending IR Codes **************** -In order to send IR signals with our remote, we can use the ``send_once`` method on -the ``lirc.Client``. +In order to send IR signals with our remote, one option we have +is that we can use the ``send_once`` method on the ``lirc.Client``. .. code-block:: python @@ -88,17 +125,50 @@ the ``lirc.Client``. client = lirc.Client() client.send_once('our-remote-name', 'key-in-the-remote-file') -Using the ``send_once()`` method is quite simple. For any method, such as this one, that -takes in a remote and a key, the parameters are always in that order with the remote -name first and then the key name. Because the ``send_once`` method does not get any meaningful -data back from lircd, there is no return value from it. Instead, as is the case for most -methods here that don't have a meaningful return value, a ``lirc.exceptions.LircdCommandFailureError`` -is raised if the command we sent failed. +Using the ``send_once()`` method is quite simple. For any method, +such as this one, that takes in a remote and a key, the parameters +are always in that order with the remote name first and then the key +name. Because the ``send_once`` method does not get any meaningful data +back from lircd, there is no return value from it. Instead, as is the case +for most methods here that don't have a meaningful return value, a +``lirc.exceptions.LircdCommandFailureError`` is raised if the command we +sent failed. -Furthermore, we can also send the key in rapid succession. This is useful if we, say, -want to go to channel 33. +Furthermore, we can also send the key in rapid succession. This is useful +if we, say, want to go to channel 33. .. code-block:: python + import lirc + + client = lirc.Client() client.send_once('our-remote-name', 'key_3', repeat_count=1) +We can also send IR codes using ``send_start`` and ``send_stop``. +``send_start`` works in a similar manner to ``send_once``. The +difference is that with ``send_start``, IR codes are continually +sent until a ``send_stop`` call. + +.. code-block:: python + + import time + import lirc + + client = lirc.Client() + client.send_start('our-remote-name', 'key_right') + time.sleep(5) + client.send_stop() + +In this example, we see that we can start sending our 'key_right' +signal for 5 seconds and then call ``send_stop`` to stop that. Notice +that we didn't pass any arguments to ``send_stop``. This is because by +default, the ``Client`` will keep track of the last remote name and +remote key that was used with ``send_start``. Optionally, we could of +made it explicit. + +.. code-block:: python + + client.send_stop('our-remote-name', 'key_right') + +This allows you to have multiple ``send_start``s running at the same time, +since you can explicitly pass in which remote and key to stop.
\ No newline at end of file |