..
 #############################################################
 # This file was automatically generated on 2015-05-08.      #
 #                                                           #
 # If you have a bugfix for this file and want to commit it, #
 # please fix the bug in the generator. You can find a link  #
 # to the generators git repository on tinkerforge.com       #
 #############################################################


:breadcrumbs: <a href="../../index.html">Home</a> / <a href="../../index.html#software-shell">Software</a> / Shell - Remote Switch Bricklet

.. |device_identifier_constant| unicode:: 0xA0
   :trim:

.. _remote_switch_bricklet_shell:

Shell - Remote Switch Bricklet
==============================

This is the description of the :ref:`Shell API bindings <api_bindings_shell>` for the :ref:`Remote Switch Bricklet <remote_switch_bricklet>`. General information and technical
specifications for the Remote Switch Bricklet are summarized in its :ref:`hardware description
<remote_switch_bricklet_description>`.

An :ref:`installation guide <api_bindings_shell_install>` for the Shell API
bindings is part of their general description.

.. _remote_switch_bricklet_shell_examples:


Examples
--------

The example code below is `Public Domain (CC0 1.0)
<http://creativecommons.org/publicdomain/zero/1.0/>`__.

Switch Socket
^^^^^^^^^^^^^

`Download (example-switch-socket.sh) <https://github.com/Tinkerforge/remote-switch-bricklet/raw/master/software/examples/shell/example-switch-socket.sh>`__

.. literalinclude:: RemoteSwitch_Bricklet_Shell_example-switch-socket.sh
 :language: bash
 :linenos:
 :tab-width: 4

.. _remote_switch_bricklet_shell_api:

API
---

Possible exit codes for all ``tinkerforge`` commands are:

* 1: interrupted (ctrl+c)
* 2: syntax error
* 21: Python 2.5 or newer is required
* 22: Python ``argparse`` module is missing
* 23: socket error
* 24: other exception
* 25: invalid placeholder in format string
* 26: authentication error
* 201: timeout occurred
* 209: invalid argument value
* 210: function is not supported
* 211: unknown error



Command Structure
^^^^^^^^^^^^^^^^^

The common options of the ``call`` and ``dispatch`` commands are documented
:ref:`here <ipcon_shell_api>`. The specific command structure is shown below.

.. sh:function:: X Stinkerforge Pcall Nremote-switch-bricklet A[<option>..] L<uid> L<function> L[<argument>..]

 :param <uid>: string
 :param <function>: string

 The ``call`` command is used to call a function of the Remote Switch Bricklet. It can take several
 options:

 * ``--help`` shows help for the specific ``call`` command and exits
 * ``--list-functions`` shows a list of known functions of the Remote Switch Bricklet and exits


.. sh:function:: X Stinkerforge Pdispatch Nremote-switch-bricklet A[<option>..] L<uid> L<callback>

 :param <uid>: string
 :param <callback>: string

 The ``dispatch`` command is used to dispatch a callback of the Remote Switch Bricklet. It can
 take several options:

 * ``--help`` shows help for the specific ``dispatch`` command and exits
 * ``--list-callbacks`` shows a list of known callbacks of the Remote Switch Bricklet and exits


.. sh:function:: X Stinkerforge Scall Premote-switch-bricklet L<uid> N<function> A[<option>..] L[<argument>..]

 :param <uid>: string
 :param <function>: string

 The ``<function>`` to be called can take different options depending of its
 kind. All functions can take the following options:

 * ``--help`` shows help for the specific function and exits

 Getter functions can take the following options:

 * ``--execute <command>`` shell command line to execute for each incoming
   response (see section about :ref:`output formatting <ipcon_shell_output>`
   for details)

 Setter functions can take the following options:

 * ``--expect-response`` requests response and waits for it

 The ``--expect-response`` option for setter functions allows to detect
 timeouts and other error conditions calls of setters as well. The device will
 then send a response for this purpose. If this option is not given for a
 setter function then no response is send and errors are silently ignored,
 because they cannot be detected.


.. sh:function:: X Stinkerforge Sdispatch Premote-switch-bricklet L<uid> N<callback> A[<option>..]

 :param <uid>: string
 :param <callback>: string

 The ``<callback>`` to be dispatched can take several options:

 * ``--help`` shows help for the specific callback and exits
 * ``--execute <command>`` shell command line to execute for each incoming
   response (see section about :ref:`output formatting <ipcon_shell_output>`
   for details)



Basic Functions
^^^^^^^^^^^^^^^



.. sh:function:: tinkerforge call remote-switch-bricklet <uid> switch-socket <house-code> <receiver-code> <switch-to> 

 :param <house-code>: int
 :param <receiver-code>: int
 :param <switch-to>: int (has symbols)

 :noreturn: no output

 This function is deprecated, use :sh:func:`switch-socket-a <remote-switch-bricklet switch-socket-a>` instead.
 
 The following symbols are available for this function:
 
 * ``off`` = 0, for <switch-to>
 * ``on`` = 1, for <switch-to>
 
.. sh:function:: tinkerforge call remote-switch-bricklet <uid> get-switching-state  


 :returns state: int (has symbols)

 Returns the current switching state. If the current state is busy, the
 Bricklet is currently sending a code to switch a socket. It will not
 accept any calls of :sh:func:`switch-socket <remote-switch-bricklet switch-socket>` until the state changes to ready.
 
 How long the switching takes is dependent on the number of repeats, see
 :sh:func:`set-repeats <remote-switch-bricklet set-repeats>`.
 
 The following symbols are available for this function:
 
 * ``ready`` = 0, for state
 * ``busy`` = 1, for state
 
.. sh:function:: tinkerforge call remote-switch-bricklet <uid> switch-socket-a <house-code> <receiver-code> <switch-to> 

 :param <house-code>: int
 :param <receiver-code>: int
 :param <switch-to>: int (has symbols)

 :noreturn: no output

 To switch a type A socket you have to give the house code, receiver code and the
 state (on or off) you want to switch to.
 
 The house code and receiver code have a range of 0 to 31 (5bit).
 
 A detailed description on how you can figure out the house and receiver code
 can be found :ref:`here <remote_switch_bricklet_type_a_house_and_receiver_code>`.
 
 The following symbols are available for this function:
 
 * ``off`` = 0, for <switch-to>
 * ``on`` = 1, for <switch-to>
 
 .. versionadded:: 2.0.1~(Plugin)
 
.. sh:function:: tinkerforge call remote-switch-bricklet <uid> switch-socket-b <address> <unit> <switch-to> 

 :param <address>: int
 :param <unit>: int
 :param <switch-to>: int (has symbols)

 :noreturn: no output

 To switch a type B socket you have to give the address, unit and the state
 (on or off) you want to switch to.
 
 The address has a range of 0 to 67108863 (26bit) and the unit has a range
 of 0 to 15 (4bit). To switch all devices with the same address use 255 for
 the unit.
 
 A detailed description on how you can teach a socket the address and unit can
 be found :ref:`here <remote_switch_bricklet_type_b_address_and_unit>`.
 
 The following symbols are available for this function:
 
 * ``off`` = 0, for <switch-to>
 * ``on`` = 1, for <switch-to>
 
 .. versionadded:: 2.0.1~(Plugin)
 
.. sh:function:: tinkerforge call remote-switch-bricklet <uid> dim-socket-b <address> <unit> <dim-value> 

 :param <address>: int
 :param <unit>: int
 :param <dim-value>: int

 :noreturn: no output

 To control a type B dimmer you have to give the address, unit and the
 dim value you want to set the dimmer to.
 
 The address has a range of 0 to 67108863 (26bit), the unit and the dim value
 has a range of 0 to 15 (4bit).
 
 A detailed description on how you can teach a dimmer the address and unit can
 be found :ref:`here <remote_switch_bricklet_type_b_address_and_unit>`.
 
 .. versionadded:: 2.0.1~(Plugin)
 
.. sh:function:: tinkerforge call remote-switch-bricklet <uid> switch-socket-c <system-code> <device-code> <switch-to> 

 :param <system-code>: char
 :param <device-code>: int
 :param <switch-to>: int (has symbols)

 :noreturn: no output

 To switch a type C socket you have to give the system code, device code and the
 state (on or off) you want to switch to.
 
 The system code has a range of 'A' to 'P' (4bit) and the device code has a
 range of 1 to 16 (4bit).
 
 A detailed description on how you can figure out the system and device code
 can be found :ref:`here <remote_switch_bricklet_type_c_system_and_device_code>`.
 
 The following symbols are available for this function:
 
 * ``off`` = 0, for <switch-to>
 * ``on`` = 1, for <switch-to>
 
 .. versionadded:: 2.0.1~(Plugin)
 


Advanced Functions
^^^^^^^^^^^^^^^^^^

.. sh:function:: tinkerforge call remote-switch-bricklet <uid> set-repeats <repeats> 

 :param <repeats>: int

 :noreturn: no output

 Sets the number of times the code is send when of the :sh:func:`switch-socket <remote-switch-bricklet switch-socket>`
 functions is called. The repeats basically correspond to the amount of time
 that a button of the remote is pressed.
 
 Some dimmers are controlled by the length of a button pressed,
 this can be simulated by increasing the repeats.
 
 The default value is 5.
 
.. sh:function:: tinkerforge call remote-switch-bricklet <uid> get-repeats  


 :returns repeats: int

 Returns the number of repeats as set by :sh:func:`set-repeats <remote-switch-bricklet set-repeats>`. 
 
.. sh:function:: tinkerforge call remote-switch-bricklet <uid> get-identity  


 :returns uid: string
 :returns connected-uid: string
 :returns position: char
 :returns hardware-version: int,int,int
 :returns firmware-version: int,int,int
 :returns device-identifier: int (has symbols)

 Returns the UID, the UID where the Bricklet is connected to, 
 the position, the hardware and firmware version as well as the
 device identifier.
 
 The position can be 'a', 'b', 'c' or 'd'.
 
 The device identifier numbers can be found :ref:`here <device_identifier>`.
 |device_identifier_constant|
 


.. _remote_switch_bricklet_shell_callbacks:

Callbacks
^^^^^^^^^

Callbacks can be used to receive time critical or recurring data from the
device:

.. code-block:: bash

    tinkerforge dispatch remote-switch-bricklet <uid> example

The available callbacks are described below.

.. note::
 Using callbacks for recurring events is *always* preferred
 compared to using getters. It will use less USB bandwidth and the latency
 will be a lot better, since there is no round trip time.

.. sh:function::  tinkerforge dispatch remote-switch-bricklet <uid> switching-done

 :noreturn: no output


 This callback is called whenever the switching state changes
 from busy to ready, see :sh:func:`get-switching-state <remote-switch-bricklet get-switching-state>`.
 


