Shell - LCD 16x2 Bricklet – Tinkerforge

- Getting Started
  - Primer
  - Tutorials
  - FAQ
- Hardware
  - Bricks
  - Bricklets
  - Master Extensions
  - Power Supplies
  - Accessories
  - Timeline
- Software
  - Brick Daemon (brickd)
  - Brick Viewer (brickv)
  - API Bindings
    - C/C++
    - C/C++ (iOS)
    - C#
    - C# (Windows Phone)
    - Delphi/Lazarus
    - Java
    - Java (Android)
    - JavaScript
    - LabVIEW
    - Mathematica
    - MATLAB/Octave
    - Perl
    - PHP
    - Python
    - Ruby
    - Shell
      - Requirements
      - Installation
      - Testing an Example
      - API Reference and Examples
        - IP Connection
        - Bricks
        - Bricklets
          - Ambient Light Bricklet
          - Analog In Bricklet
          - Analog Out Bricklet
          - Barometer Bricklet
          - Color Bricklet
          - Current12 Bricklet
          - Current25 Bricklet
          - Distance IR Bricklet
          - Distance US Bricklet
          - Dual Button Bricklet
          - Dual Relay Bricklet
          - GPS Bricklet
          - Hall Effect Bricklet
          - Humidity Bricklet
          - Industrial Digital In 4 Bricklet
          - Industrial Digital Out 4 Bricklet
          - Industrial Dual 0-20mA Bricklet
          - Industrial Quad Relay Bricklet
          - IO-16 Bricklet
          - IO-4 Bricklet
          - Joystick Bricklet
          - LCD 16x2 Bricklet
            - Examples
              - Hello World
              - Button Callbacks
              - Unicode
            - API
              - Command Structure
              - Basic Functions
              - Advanced Functions
              - Callbacks
          - LCD 20x4 Bricklet
          - LED Strip Bricklet
          - Line Bricklet
          - Linear Poti Bricklet
          - Moisture Bricklet
          - Motion Detector Bricklet
          - Multi Touch Bricklet
          - NFC/RFID Bricklet
          - Piezo Buzzer Bricklet
          - Piezo Speaker Bricklet
          - PTC Bricklet
          - Remote Switch Bricklet
          - Rotary Encoder Bricklet
          - Rotary Poti Bricklet
          - Segment Display 4x7 Bricklet
          - Solid State Relay Bricklet
          - Sound Intensity Bricklet
          - Temperature Bricklet
          - Temperature IR Bricklet
          - Tilt Bricklet
          - Voltage Bricklet
          - Voltage/Current Bricklet
    - Visual Basic .NET
  - Firmwares and Plugins
  - Device Identifier
  - Source Code and Bug Tracking
  - Programming Interface
- Starter Kits
  - Weather Station
  - Hardware Hacking
  - Server Room Monitoring
  - Blinkenlights
  - Internet of Things
  - Camera Slider
- Embedded Boards
  - Raspberry Pi
- Specifications
  - Technical Data
  - TCP/IP Protocol
  - Modbus Protocol
  - Wireshark Dissector

# Shell - LCD 16x2 Bricklet

This is the description of the Shell API bindings for the LCD 16x2 Bricklet. General information and technical specifications for the LCD 16x2 Bricklet are summarized in its hardware description.

An installation guide for the Shell API bindings is part of their general description.

## Examples

The example code below is Public Domain (CC0 1.0).

### Hello World

Download (example-hello-world.sh)

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11

    #!/bin/sh
    # connects to localhost:4223 by default, use --host and --port to change it

    # change to your UID
    uid=XYZ

    # turn backlight on
    tinkerforge call lcd-16x2-bricklet $uid backlight-on

    # write "Hello World"
    tinkerforge call lcd-16x2-bricklet $uid write-line 0 0 "Hello World"

### Button Callbacks

Download (example-button-callbacks.sh)

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13

    #!/bin/sh
    # connects to localhost:4223 by default, use --host and --port to change it

    # change to your UID
    uid=XYZ

    # handle incoming pressed and released callbacks
    # note: this chaining of two dispatches assumes that a pressed callback is
    #       always followed by a released callback for the same button
    tinkerforge dispatch lcd-16x2-bricklet $uid button-pressed\
     --execute "echo Pressed: {button};
                tinkerforge dispatch --duration exit-after-first lcd-16x2-bricklet $uid button-released\
                 --execute 'echo Released: {button}'"

### Unicode

Download (example-unicode.sh)

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17

    #!/bin/sh
    # connects to localhost:4223 by default, use --host and --port to change it

    # change to your UID
    uid=XYZ

    # turn backlight on
    tinkerforge call lcd-16x2-bricklet $uid backlight-on

    # write some strings using sed to map to the LCD charset
    # note: this assumes that the shell supports UTF-8
    tinkerforge call lcd-16x2-bricklet $uid write-line 0 0\
     "`echo 'Stromstärke: 5µA' | sed 'y/\o134~¥→←°αÄäßεµςρ√¹¤¢ⱠñÖöϴ∞ΩÜüΣπ÷■/\o244\o55\o134\o176\o177\o337\o340\o341\o341\o342\o343\o344\o345\o346\o350\o351\o353\o354\o355\o356\o357\o357\o362\o363\o364\o365\o365\o366\o367\o375\o377/'`"

    # write a string directly including characters from the LCD charset
    tinkerforge call lcd-16x2-bricklet $uid write-line 1 0\
     "`echo -e 'Drehzahl: 1000s\xe9'`"

## 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 here. The specific command structure is shown below.

tinkerforge `call` `lcd-16x2-bricklet` [<option>..] <uid> <function> [<argument>..]

  Parameters:

  - <uid> -- string
  - <function> -- string

  The `call` command is used to call a function of the LCD 16x2 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 LCD 16x2 Bricklet and exits

tinkerforge `dispatch` `lcd-16x2-bricklet` [<option>..] <uid> <callback>

  Parameters:

  - <uid> -- string
  - <callback> -- string

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

tinkerforge call `lcd-16x2-bricklet` <uid> `<function>` [<option>..] [<argument>..]

  Parameters:

  - <uid> -- string
  - <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 output formatting 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.

tinkerforge dispatch `lcd-16x2-bricklet` <uid> `<callback>` [<option>..]

  Parameters:

  - <uid> -- string
  - <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 output formatting for details)

### Basic Functions

tinkerforge call `lcd-16x2-bricklet` <uid> `write-line` <line> <position> <text>

  Parameters:

  - <line> -- int
  - <position> -- int
  - <text> -- string

  Output: | no output

  Writes text to a specific line (0 to 1) with a specific position (0 to 15). The text can have a maximum of 16 characters.

  For example: (0, 5, "Hello") will write Hello in the middle of the first line of the display.

  The display uses a special charset that includes all ASCII characters except backslash and tilde. The LCD charset also includes several other non-ASCII characters, see the charset specification for details. The Unicode example above shows how to specify non-ASCII characters and how to translate from Unicode to the LCD charset.

tinkerforge call `lcd-16x2-bricklet` <uid> `clear-display`

  Output: | no output

  Deletes all characters from the display.

tinkerforge call `lcd-16x2-bricklet` <uid> `backlight-on`

  Output: | no output

  Turns the backlight on.

tinkerforge call `lcd-16x2-bricklet` <uid> `backlight-off`

  Output: | no output

  Turns the backlight off.

tinkerforge call `lcd-16x2-bricklet` <uid> `is-backlight-on`

  Output:

  - backlight -- bool

  Returns true if the backlight is on and false otherwise.

### Advanced Functions

tinkerforge call `lcd-16x2-bricklet` <uid> `set-config` <cursor> <blinking>

  Parameters:

  - <cursor> -- bool
  - <blinking> -- bool

  Output: | no output

  Configures if the cursor (shown as "_") should be visible and if it should be blinking (shown as a blinking block). The cursor position is one character behind the the last text written with `write-line`.

  The default is (false, false).

tinkerforge call `lcd-16x2-bricklet` <uid> `get-config`

  Output:

  - cursor -- bool
  - blinking -- bool

  Returns the configuration as set by `set-config`.

tinkerforge call `lcd-16x2-bricklet` <uid> `is-button-pressed` <button>

  Parameters:

  - <button> -- int

  Output:

  - pressed -- bool

  Returns true if the button (0 to 2) is pressed. If you want to react on button presses and releases it is recommended to use the `button-pressed` and `button-released` callbacks.

tinkerforge call `lcd-16x2-bricklet` <uid> `set-custom-character` <index> <character>

  Parameters:

  - <index> -- int
  - <character> -- int,int,int,int,int,int,int,int

  Output: | no output

  The LCD 16x2 Bricklet can store up to 8 custom characters. The characters consist of 5x8 pixels and can be addressed with the index 0-7. To describe the pixels, the first 5 bits of 8 bytes are used. For example, to make a custom character "H", you should transfer the following:

  - `character[0] = 0b00010001` (decimal value 17)
  - `character[1] = 0b00010001` (decimal value 17)
  - `character[2] = 0b00010001` (decimal value 17)
  - `character[3] = 0b00011111` (decimal value 31)
  - `character[4] = 0b00010001` (decimal value 17)
  - `character[5] = 0b00010001` (decimal value 17)
  - `character[6] = 0b00010001` (decimal value 17)
  - `character[7] = 0b00000000` (decimal value 0)

  The characters can later be written with `write-line` by using the characters with the byte representation 8 to 15.

  You can play around with the custom characters in Brick Viewer since version 2.0.1.

  Custom characters are stored by the LCD in RAM, so they have to be set after each startup.

  New in version 2.0.1 (Plugin).

tinkerforge call `lcd-16x2-bricklet` <uid> `get-custom-character` <index>

  Parameters:

  - <index> -- int

  Output:

  - character -- int,int,int,int,int,int,int,int

  Returns the custom character for a given index, as set with `set-custom-character`.

  New in version 2.0.1 (Plugin).

tinkerforge call `lcd-16x2-bricklet` <uid> `get-identity`

  Output:

  - uid -- string
  - connected-uid -- string
  - position -- char
  - hardware-version -- int,int,int
  - firmware-version -- int,int,int
  - 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 here.

### Callbacks

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

    tinkerforge dispatch lcd-16x2-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.

tinkerforge dispatch `lcd-16x2-bricklet` <uid> `button-pressed`

  Output:

  - button -- int

  This callback is triggered when a button is pressed. The parameter is the number of the button (0 to 2).

tinkerforge dispatch `lcd-16x2-bricklet` <uid> `button-released`

  Output:

  - button -- int

  This callback is triggered when a button is released. The parameter is the number of the button (0 to 2).

The content of this page is licensed under Creative Commons Attribution 3.0 Unported License.