Class: Tinkerforge::BrickletLCD20x4

Inherits:
Device
  • Object
show all
Defined in:
lib/tinkerforge/bricklet_lcd_20x4.rb

Overview

20x4 character alphanumeric display with blue backlight

Constant Summary collapse

DEVICE_IDENTIFIER =

:nodoc:

212
DEVICE_DISPLAY_NAME =

:nodoc:

'LCD 20x4 Bricklet'
CALLBACK_BUTTON_PRESSED =

This callback is triggered when a button is pressed. The parameter is the number of the button (0 to 2 or 0 to 3 since hardware version 1.2).

9
CALLBACK_BUTTON_RELEASED =

This callback is triggered when a button is released. The parameter is the number of the button (0 to 2 or 0 to 3 since hardware version 1.2).

10
FUNCTION_WRITE_LINE =

:nodoc:

1
FUNCTION_CLEAR_DISPLAY =

:nodoc:

2
FUNCTION_BACKLIGHT_ON =

:nodoc:

3
FUNCTION_BACKLIGHT_OFF =

:nodoc:

4
FUNCTION_IS_BACKLIGHT_ON =

:nodoc:

5
FUNCTION_SET_CONFIG =

:nodoc:

6
FUNCTION_GET_CONFIG =

:nodoc:

7
FUNCTION_IS_BUTTON_PRESSED =

:nodoc:

8
FUNCTION_SET_CUSTOM_CHARACTER =

:nodoc:

11
FUNCTION_GET_CUSTOM_CHARACTER =

:nodoc:

12
FUNCTION_SET_DEFAULT_TEXT =

:nodoc:

13
FUNCTION_GET_DEFAULT_TEXT =

:nodoc:

14
FUNCTION_SET_DEFAULT_TEXT_COUNTER =

:nodoc:

15
FUNCTION_GET_DEFAULT_TEXT_COUNTER =

:nodoc:

16
FUNCTION_GET_IDENTITY =

:nodoc:

255

Constants inherited from Device

Device::DEVICE_IDENTIFIER_CHECK_MATCH, Device::DEVICE_IDENTIFIER_CHECK_MISMATCH, Device::DEVICE_IDENTIFIER_CHECK_PENDING, Device::RESPONSE_EXPECTED_ALWAYS_TRUE, Device::RESPONSE_EXPECTED_FALSE, Device::RESPONSE_EXPECTED_INVALID_FUNCTION_ID, Device::RESPONSE_EXPECTED_TRUE

Instance Attribute Summary

Attributes inherited from Device

#callback_formats, #expected_response_function_id, #expected_response_sequence_number, #high_level_callbacks, #registered_callbacks, #replaced, #uid

Instance Method Summary collapse

Methods inherited from Device

#check_validity, #dequeue_response, #enqueue_response, #get_api_version, #get_response_expected, #send_request, #set_response_expected, #set_response_expected_all

Constructor Details

#initialize(uid, ipcon) ⇒ BrickletLCD20x4

Creates an object with the unique device ID uid and adds it to the IP Connection ipcon.



47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
 
# File 'lib/tinkerforge/bricklet_lcd_20x4.rb', line 47

def initialize(uid, ipcon)
  super uid, ipcon, DEVICE_IDENTIFIER, DEVICE_DISPLAY_NAME

  @api_version = [2, 0, 2]

  @response_expected[FUNCTION_WRITE_LINE] = RESPONSE_EXPECTED_FALSE
  @response_expected[FUNCTION_CLEAR_DISPLAY] = RESPONSE_EXPECTED_FALSE
  @response_expected[FUNCTION_BACKLIGHT_ON] = RESPONSE_EXPECTED_FALSE
  @response_expected[FUNCTION_BACKLIGHT_OFF] = RESPONSE_EXPECTED_FALSE
  @response_expected[FUNCTION_IS_BACKLIGHT_ON] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[FUNCTION_SET_CONFIG] = RESPONSE_EXPECTED_FALSE
  @response_expected[FUNCTION_GET_CONFIG] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[FUNCTION_IS_BUTTON_PRESSED] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[FUNCTION_SET_CUSTOM_CHARACTER] = RESPONSE_EXPECTED_FALSE
  @response_expected[FUNCTION_GET_CUSTOM_CHARACTER] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[FUNCTION_SET_DEFAULT_TEXT] = RESPONSE_EXPECTED_FALSE
  @response_expected[FUNCTION_GET_DEFAULT_TEXT] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[FUNCTION_SET_DEFAULT_TEXT_COUNTER] = RESPONSE_EXPECTED_FALSE
  @response_expected[FUNCTION_GET_DEFAULT_TEXT_COUNTER] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[FUNCTION_GET_IDENTITY] = RESPONSE_EXPECTED_ALWAYS_TRUE

  @callback_formats[CALLBACK_BUTTON_PRESSED] = [9, 'C']
  @callback_formats[CALLBACK_BUTTON_RELEASED] = [9, 'C']

  @ipcon.add_device self
end

Instance Method Details

#backlight_off ⇒ Object

Turns the backlight off.



106
107
108
109
110
 
# File 'lib/tinkerforge/bricklet_lcd_20x4.rb', line 106

def backlight_off
  check_validity

  send_request FUNCTION_BACKLIGHT_OFF, [], '', 8, ''
end

#backlight_on ⇒ Object

Turns the backlight on.



99
100
101
102
103
 
# File 'lib/tinkerforge/bricklet_lcd_20x4.rb', line 99

def backlight_on
  check_validity

  send_request FUNCTION_BACKLIGHT_ON, [], '', 8, ''
end

#clear_display ⇒ Object

Deletes all characters from the display.



92
93
94
95
96
 
# File 'lib/tinkerforge/bricklet_lcd_20x4.rb', line 92

def clear_display
  check_validity

  send_request FUNCTION_CLEAR_DISPLAY, [], '', 8, ''
end

#get_config ⇒ Object

Returns the configuration as set by BrickletLCD20x4#set_config.



130
131
132
133
134
 
# File 'lib/tinkerforge/bricklet_lcd_20x4.rb', line 130

def get_config
  check_validity

  send_request FUNCTION_GET_CONFIG, [], '', 10, '? ?'
end

#get_custom_character(index) ⇒ Object

Returns the custom character for a given index, as set with BrickletLCD20x4#set_custom_character.

.. versionadded

2.0.1$nbsp;(Plugin)



182
183
184
185
186
 
# File 'lib/tinkerforge/bricklet_lcd_20x4.rb', line 182

def get_custom_character(index)
  check_validity

  send_request FUNCTION_GET_CUSTOM_CHARACTER, [index], 'C', 16, 'C8'
end

#get_default_text(line) ⇒ Object

Returns the default text for a given line (0-3) as set by BrickletLCD20x4#set_default_text.

.. versionadded

2.0.2$nbsp;(Plugin)



205
206
207
208
209
 
# File 'lib/tinkerforge/bricklet_lcd_20x4.rb', line 205

def get_default_text(line)
  check_validity

  send_request FUNCTION_GET_DEFAULT_TEXT, [line], 'C', 28, 'Z20'
end

#get_default_text_counter ⇒ Object

Returns the current value of the default text counter.

.. versionadded

2.0.2$nbsp;(Plugin)



235
236
237
238
239
 
# File 'lib/tinkerforge/bricklet_lcd_20x4.rb', line 235

def get_default_text_counter
  check_validity

  send_request FUNCTION_GET_DEFAULT_TEXT_COUNTER, [], '', 12, 'l'
end

#get_identity ⇒ Object

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’, ‘d’, ‘e’, ‘f’, ‘g’ or ‘h’ (Bricklet Port). A Bricklet connected to an :ref:‘Isolator Bricklet <isolator_bricklet>` is always at position ’z’.

The device identifier numbers can be found :ref:‘here <device_identifier>`. |device_identifier_constant|



251
252
253
 
# File 'lib/tinkerforge/bricklet_lcd_20x4.rb', line 251

def get_identity
  send_request FUNCTION_GET_IDENTITY, [], '', 33, 'Z8 Z8 k C3 C3 S'
end

#is_backlight_on ⇒ Object

Returns true if the backlight is on and false otherwise.



113
114
115
116
117
 
# File 'lib/tinkerforge/bricklet_lcd_20x4.rb', line 113

def is_backlight_on
  check_validity

  send_request FUNCTION_IS_BACKLIGHT_ON, [], '', 9, '?'
end

#is_button_pressed(button) ⇒ Object

Returns true if the button (0 to 2 or 0 to 3 since hardware version 1.2) is pressed.

If you want to react on button presses and releases it is recommended to use the CALLBACK_BUTTON_PRESSED and CALLBACK_BUTTON_RELEASED callbacks.



141
142
143
144
145
 
# File 'lib/tinkerforge/bricklet_lcd_20x4.rb', line 141

def is_button_pressed(button)
  check_validity

  send_request FUNCTION_IS_BUTTON_PRESSED, [button], 'C', 9, '?'
end

#register_callback(id, &block) ⇒ Object

Registers a callback with ID id to the block block.



256
257
258
259
 
# File 'lib/tinkerforge/bricklet_lcd_20x4.rb', line 256

def register_callback(id, &block)
  callback = block
  @registered_callbacks[id] = callback
end

#set_config(cursor, blinking) ⇒ Object

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 BrickletLCD20x4#write_line.



123
124
125
126
127
 
# File 'lib/tinkerforge/bricklet_lcd_20x4.rb', line 123

def set_config(cursor, blinking)
  check_validity

  send_request FUNCTION_SET_CONFIG, [cursor, blinking], '? ?', 8, ''
end

#set_custom_character(index, character) ⇒ Object

The LCD 20x4 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 = 0b00010001“ (decimal value 17)

  • “character = 0b00010001“ (decimal value 17)

  • “character = 0b00010001“ (decimal value 17)

  • “character = 0b00011111“ (decimal value 31)

  • “character = 0b00010001“ (decimal value 17)

  • “character = 0b00010001“ (decimal value 17)

  • “character = 0b00010001“ (decimal value 17)

  • “character = 0b00000000“ (decimal value 0)

The characters can later be written with BrickletLCD20x4#write_line by using the characters with the byte representation 8 (“\x08” or “\u0008”) to 15 (“\x0F” or “\u000F”).

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

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

.. versionadded

2.0.1$nbsp;(Plugin)



172
173
174
175
176
 
# File 'lib/tinkerforge/bricklet_lcd_20x4.rb', line 172

def set_custom_character(index, character)
  check_validity

  send_request FUNCTION_SET_CUSTOM_CHARACTER, [index, character], 'C C8', 8, ''
end

#set_default_text(line, text) ⇒ Object

Sets the default text for lines 0-3. The max number of characters per line is 20.

The default text is shown on the LCD, if the default text counter expires, see BrickletLCD20x4#set_default_text_counter.

.. versionadded

2.0.2$nbsp;(Plugin)



195
196
197
198
199
 
# File 'lib/tinkerforge/bricklet_lcd_20x4.rb', line 195

def set_default_text(line, text)
  check_validity

  send_request FUNCTION_SET_DEFAULT_TEXT, [line, text], 'C Z20', 8, ''
end

#set_default_text_counter(counter) ⇒ Object

Sets the default text counter. This counter is decremented each ms by the LCD firmware. If the counter reaches 0, the default text (see BrickletLCD20x4#set_default_text) is shown on the LCD.

This functionality can be used to show a default text if the controlling program crashes or the connection is interrupted.

A possible approach is to call BrickletLCD20x4#set_default_text_counter every minute with the parameter 1000*60*2 (2 minutes). In this case the default text will be shown no later than 2 minutes after the controlling program crashes.

A negative counter turns the default text functionality off.

.. versionadded

2.0.2$nbsp;(Plugin)



226
227
228
229
230
 
# File 'lib/tinkerforge/bricklet_lcd_20x4.rb', line 226

def set_default_text_counter(counter)
  check_validity

  send_request FUNCTION_SET_DEFAULT_TEXT_COUNTER, [counter], 'l', 8, ''
end

#write_line(line, position, text) ⇒ Object

Writes text to a specific line with a specific position. The text can have a maximum of 20 characters.

For example: (0, 7, “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 <github.com/Tinkerforge/lcd-20x4-bricklet/raw/master/datasheets/standard_charset.pdf>`__ for details. The Unicode example above shows how to specify non-ASCII characters and how to translate from Unicode to the LCD charset.



85
86
87
88
89
 
# File 'lib/tinkerforge/bricklet_lcd_20x4.rb', line 85

def write_line(line, position, text)
  check_validity

  send_request FUNCTION_WRITE_LINE, [line, position, text], 'C C Z20', 8, ''
end