..
 #############################################################
 # 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 - Hall Effect Bricklet

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

.. _hall_effect_bricklet_shell:

Shell - Hall Effect Bricklet
============================

This is the description of the :ref:`Shell API bindings <api_bindings_shell>` for the :ref:`Hall Effect Bricklet <hall_effect_bricklet>`. General information and technical
specifications for the Hall Effect Bricklet are summarized in its :ref:`hardware description
<hall_effect_bricklet_description>`.

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

.. _hall_effect_bricklet_shell_examples:


Examples
--------

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

Simple
^^^^^^

`Download (example-simple.sh) <https://github.com/Tinkerforge/hall-effect-bricklet/raw/master/software/examples/shell/example-simple.sh>`__

.. literalinclude:: HallEffect_Bricklet_Shell_example-simple.sh
 :language: bash
 :linenos:
 :tab-width: 4

Callback
^^^^^^^^

`Download (example-callback.sh) <https://github.com/Tinkerforge/hall-effect-bricklet/raw/master/software/examples/shell/example-callback.sh>`__

.. literalinclude:: HallEffect_Bricklet_Shell_example-callback.sh
 :language: bash
 :linenos:
 :tab-width: 4

.. _hall_effect_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 Nhall-effect-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 Hall Effect 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 Hall Effect Bricklet and exits


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

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

 The ``dispatch`` command is used to dispatch a callback of the Hall Effect 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 Hall Effect Bricklet and exits


.. sh:function:: X Stinkerforge Scall Phall-effect-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 Phall-effect-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 hall-effect-bricklet <uid> get-value  


 :returns value: bool

 Returns *true* if a magnetic field of 35 Gauss (3.5mT) or greater is detected.
 
.. sh:function:: tinkerforge call hall-effect-bricklet <uid> get-edge-count <reset-counter> 

 :param <reset-counter>: bool

 :returns count: int

 Returns the current value of the edge counter. You can configure
 edge type (rising, falling, both) that is counted with
 :sh:func:`set-edge-count-config <hall-effect-bricklet set-edge-count-config>`.
 
 If you set the reset counter to *true*, the count is set back to 0
 directly after it is read.
 


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

.. sh:function:: tinkerforge call hall-effect-bricklet <uid> set-edge-count-config <edge-type> <debounce> 

 :param <edge-type>: int (has symbols)
 :param <debounce>: int

 :noreturn: no output

 The edge type parameter configures if rising edges, falling edges or 
 both are counted. Possible edge types are:
 
 * 0 = rising (default)
 * 1 = falling
 * 2 = both
 
 A magnetic field of 35 Gauss (3.5mT) or greater causes a falling edge and a
 magnetic field of 25 Gauss (2.5mT) or smaller causes a rising edge.
 
 If a magnet comes near the Bricklet the signal goes low (falling edge), if
 a magnet is removed from the vicinity the signal goes high (rising edge).
 
 The debounce time is given in ms.
 
 Configuring an edge counter resets its value to 0.
 
 If you don't know what any of this means, just leave it at default. The
 default configuration is very likely OK for you.
 
 Default values: 0 (edge type) and 100ms (debounce time)
 
 The following symbols are available for this function:
 
 * ``rising`` = 0, for <edge-type>
 * ``falling`` = 1, for <edge-type>
 * ``both`` = 2, for <edge-type>
 
.. sh:function:: tinkerforge call hall-effect-bricklet <uid> get-edge-count-config  


 :returns edge-type: int (has symbols)
 :returns debounce: int

 Returns the edge type and debounce time as set by :sh:func:`set-edge-count-config <hall-effect-bricklet set-edge-count-config>`.
 
 The following symbols are available for this function:
 
 * ``rising`` = 0, for edge-type
 * ``falling`` = 1, for edge-type
 * ``both`` = 2, for edge-type
 
.. sh:function:: tinkerforge call hall-effect-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|
 


Callback Configuration Functions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^



.. sh:function:: tinkerforge call hall-effect-bricklet <uid> set-edge-interrupt <edges> 

 :param <edges>: int

 :noreturn: no output

 Sets the number of edges until an interrupt is invoked.
 
 If *edges* is set to n, an interrupt is invoked for every n-th detected edge.
 
 If *edges* is set to 0, the interrupt is disabled.
 
 Default value is 0.
 
.. sh:function:: tinkerforge call hall-effect-bricklet <uid> get-edge-interrupt  


 :returns edges: int

 Returns the edges as set by :sh:func:`set-edge-interrupt <hall-effect-bricklet set-edge-interrupt>`.
 
.. sh:function:: tinkerforge call hall-effect-bricklet <uid> set-edge-count-callback-period <period> 

 :param <period>: int

 :noreturn: no output

 Sets the period in ms with which the :sh:func:`edge-count <hall-effect-bricklet edge-count>` callback is triggered
 periodically. A value of 0 turns the callback off.
 
 :sh:func:`edge-count <hall-effect-bricklet edge-count>` is only triggered if the edge count has changed since the
 last triggering.
 
 The default value is 0.
 
.. sh:function:: tinkerforge call hall-effect-bricklet <uid> get-edge-count-callback-period  


 :returns period: int

 Returns the period as set by :sh:func:`set-edge-count-callback-period <hall-effect-bricklet set-edge-count-callback-period>`.
 


.. _hall_effect_bricklet_shell_callbacks:

Callbacks
^^^^^^^^^

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

.. code-block:: bash

    tinkerforge dispatch hall-effect-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 hall-effect-bricklet <uid> edge-count

 :returns count: int
 :returns value: bool


 This callback is triggered periodically with the period that is set by
 :sh:func:`set-edge-count-callback-period <hall-effect-bricklet set-edge-count-callback-period>`. The parameters are the
 current count and the current value (see :sh:func:`get-value <hall-effect-bricklet get-value>` and :sh:func:`get-edge-count <hall-effect-bricklet get-edge-count>`).
 
 :sh:func:`edge-count <hall-effect-bricklet edge-count>` is only triggered if the count or value changed since the
 last triggering.
 


