Latest Version: 2.0.0
This library provides support for CrystalFontz CFA533 and CFA633 serial LCD displays. The CFAx33 series integrates a keypad and the LCD with a simple UART interface. The display lines can be written or cleared individually or together, and the backlight is controllable. Keypress callbacks can be attached to a class instance to handle specific key presses.
The CFA533 is used in Electric Imp’s impFactory™ product.
You can view the library’s source code on GitHub. Click here to see information on other versions of this library.
To add this library to your project, add #require "CFAx33KL.device.lib.nut:2.0.0" to the top of your device code
The constructor takes one (required) parameter: an imp UART object which will be configured by the constructor.
#require "CFAx33KL.device.lib.nut:2.0.0"
lcd <- CFAx33KL(hardware.uart6E);
Most methods in this library contain an optional parameter, callback. If a callback function is passed in, it will be called when the CFAx33 acknowledges the command. The callback function has one parameter of its own: a response table. This table will contain either an err key with an error message, or a msg key with the data received from the response packet. If no response data is expected, a successful response often contains an empty array as the value of msg.
The display features two 16-character rows. The setText() method uses the column and row parameters to position the text that will be displayed (the value of text). The column parameter determines the starting position of the text, and can be any integer from 0 to 15. The length of the text plus the column value must be less than 16 or the text will be truncated. The row can be either 0, to display text on the first row, or 1, to display text on the second row.
An optional callback can also be provided; please see ‘Optional Callbacks’ for details.
lcd.setText(0, 0, "Hello World!", function(response) {
if ("err" in response) {
server.error(response.err);
} else {
server.log("Text received by display");
}
});
This method clears the first line of the display and sets it to the string text. The maximum length of the string is 16 characters; the text will be truncated if the string is longer than 16 characters. The optional callback function will be called when the CFAx33KL acknowledges the command; please see ‘Optional Callbacks’ for details.
This method clears the second line of the display and sets it to the string text. The maximum length of the string is 16 characters; the text will be truncated if the string is longer than 16 characters. The optional callback function will be called when the CFAx33KL acknowledges the command; please see ‘Optional Callbacks’ for details.
lcd.setLine1("Hello, World!");
lcd.setLine2("I'm a CFAx33KL LCD");
This method clears the entire display. The optional callback function will be called when the CFAx33KL acknowledges the command; please see ‘Optional Callbacks’ for details.
This method clears the first line of the display. The optional callback function will be called when the CFAx33KL acknowledges the command; please see ‘Optional Callbacks’ for details.
This method clears the second line of the display. The optional callback function will be called when the CFAx33KL acknowledges the command; please see ‘Optional Callbacks’ for details.
This method sets the keypad and LCD backlight brightness to the value of brightness. The value should be a percentage between 0 (backlight off) and 100 (max brightness).
If you are using a CFA533 unit, you can pass either a single integer, as above, or an array of two integers. If one value is supplied, both the keypad and LCD backlights will be set to that brightness. If two values are supplied as an array, the first value will set the LCD brightness and the second value will set the keypad brightness.
The CFA633 only supports the single value brightness control.
The optional callback function will be called when the CFAx33KL acknowledges the command; please see ‘Optional Callbacks’ for details.
// Set 50% brightness
lcd.setBrightness(50);
// Set LCD to 20% and keypad 5% brightness
lcd.setBrightness([20, 5]);
This method sets the backlight contrast to the value of contrast, which should be between 0 (no contrast, ie. text invisible) and 50 (maximum contrast, ie. fully black). The recommended value is 16. setContrast() only supports the one-byte “CFA633 Compatible” version of the command. The optional callback function will be called when the CFAx33KL acknowledges the command; please see ‘Optional Callbacks’ for details.
| Contrast Value | Text Presentation |
|---|---|
| 0 | Invisible |
| 1 | Light |
| 16 | Recommended |
| 29 | Dark |
| 30-50 | Very dark |
// Set 16% contrast
lcd.setContrast(16);
This method saves the current state of the LCD — text, brightness and contrast — to non-volatile memory so that it can be displayed when the display powers up. The optional callback function will be called when the CFAx33KL acknowledges the command; please see ‘Optional Callbacks’ for details.
// Store a useful boot-up message and state
// to be displayed on power-on
lcd.clearAll();
lcd.setLine1("Electric Imp");
lcd.setLine2("Is Excellent!");
lcd.setBrightness(20);
lcd.setContrast(12);
lcd.storeCurrentStateAsBootState();
This method registers a callback function that will be executed when a keypress event is received from the CFAx33KL. The callback has one paramater of its own into which one of the following CFAx33KL_KEY_
To clear a previously registered callback pass in null instead of a callback function.
// Test the LCD's integrated keys
lcd.setLine1("Key Test");
lcd.clearLine2();
lcd.onKeyEvent(function(key) {
if (key == CFAx33KL_KEY_UP_PRESS) {
lcd.setLine2("UP Pressed");
} else if (key == CFAx33KL_KEY_DOWN_PRESS) {
lcd.setLine2("DOWN Pressed");
} else if (key == CFAx33KL_KEY_LEFT_PRESS) {
lcd.setLine2("LEFT Pressed");
} else if (key == CFAx33KL_KEY_RIGHT_PRESS) {
lcd.setLine2("RIGHT Pressed");
} else if (key == CFAx33KL_KEY_ENTER_PRESS) {
lcd.setLine2("OK Pressed");
} else if (key == CFAx33KL_KEY_EXIT_PRESS) {
lcd.setLine2("EXIT Pressed");
} else if (key == CFAx33KL_KEY_UP_RELEASE) {
lcd.setLine2("UP Released");
} else if (key == CFAx33KL_KEY_DOWN_RELEASE) {
lcd.setLine2("DOWN Released");
} else if (key == CFAx33KL_KEY_LEFT_RELEASE) {
lcd.setLine2("LEFT Released");
} else if (key == CFAx33KL_KEY_RIGHT_RELEASE) {
lcd.setLine2("RIGHT Released");
} else if (key == CFAx33KL_KEY_ENTER_RELEASE) {
lcd.setLine2("OK Released");
} else if (key == CFAx33KL_KEY_EXIT_RELEASE) {
lcd.setLine2("EXIT Released");
} else {
lcd.setLine2("Unknown Key!");
}
});
This method’s keyName parameter takes one of the following CFAx33KL_KEY_true if the key is currently pressed, otherwise false.
server.log("Up key is " + (lcd.getKeyState(CFAx33KL_KEY_UP) ? "" : "not ") + "pressed");
This method registers a callback function that will be executed when an error is encountered. The callback has one parameter of its own into which a string containing a description of the error will be placed.
To clear a previously set callback pass in null instead of a callback function.
lcd.onError(function(errorString) {
server.error(errorString);
});
This method retrieves the display’s hardware and firmware version and passes the response to the callback. The callback takes one parameter: a table containing either version or err keys. For the CFA633, the version is formatted "CFA633:hX.X,yY.Y", where hX.X is the hardware revision and yY.Y is the firmware version. For the CFA533, the version is formatted "CFA533:XhX,YsY".
lcd.getVersion(function(response) {
if ("err" in response) {
server.error(response.err);
} else {
server.log(response.version);
}
});
The Electric Imp Dev Center documents the latest version of the library. For past versions, please see the Electric Imp public GitHub repos listed below.
| Version | Source Code | Notes |
|---|---|---|
| 1.0.1 | GitHub | Initial release |
| 1.1.0 | GitHub | Add getVersion() method; limit contrast to 50; add support for separate LCD and keypad brightness settings; handle overlong text better: truncate string rather than throw runtime errors |
| 2.0.0 | GitHub | Renamed using new library naming scheme; add getKeyState() |
The CFAx33 library is available under the MIT License.