====== Character LCD Guide ======

A character LCD shows letters and numbers line by line. This guide explains how to use **an HD44780-compatible character LCD fitted with a PCF8574 I²C adapter module** with the built-in ''Iclcd...()'' functions on ILOGICS industrial Arduino products. You do not need to add ''ILIB.h'', ''CLCD.h'', ''Wire.h'', or an LCD object to your sketch.

Check the connections in the order below, enter your LCD's actual **I²C address and number of columns and rows**, then upload the example. The address ''0x27'' and the size ''20 × 4'' are example values on this page, not values shared by every LCD. **A 16 × 4 LCD is outside the scope of this guide, because rows 3 and 4 do not match the positions the built-in functions calculate.**

===== 1. Prepare and connect =====

  - Install the ILOGICS Arduino SDK as described in [[:en-us_guide:getting_started|Getting Started with Arduino IDE]], and select the board and port for your product.
  - **With the power off**, connect the product's I²C terminals to the LCD adapter module. See your [[:en-us_products:mpino_series|MPINO]] or [[:en-us_products:mpaino|MPAINO]] product page for the terminal location and power output rating.

^ Signal printed on the LCD adapter module ^ Product I²C terminal ^ What to check ^
| ''SDA'' | ''SDA'' | Connect the data signals together. |
| ''SCL'' | ''SCL'' | Connect the clock signals together. |
| ''VCC'' or ''+5V'' | ''+5V'' | Connect **only if the LCD adapter module takes 5 V**. First check the +5V terminal of your product and the module's power rating. |
| ''GND'' | ''GND'' | Connect the grounds together. |

On MPINO-16A8R, take ''+5V'' and ''GND'' from the POWER terminal. Its +5V output is limited to 100 mA, so first check the LCD's current, including the backlight.

The figure shows the part of the **MPAINO CPU module I²C wiring diagram** needed for the LCD. The diagram and terminal information come from the [[:en-us_products:mpaino_16a16r|MPAINO-16A16R product page]].

{{ :en-us_guide:character_lcd:mpaino-i2c-connection.svg?500 |Connecting the MPAINO CPU module I²C terminals to a device's SDA, SCL, +5V, and GND by matching names }}

On the MPAINO CPU module, ''SDA'' is ''D20'' and ''SCL'' is ''D21''. **Numeric pin numbers on MPINO differ by model**, so do not apply these values to MPINO. Follow the actual ''SDA'' and ''SCL'' terminals and the product page. While using I²C, do not use the same ''SDA'' and ''SCL'' as external interrupt or encoder inputs.

===== 2. Built-in functions =====

Initialize the LCD with ''IclcdBegin(address, columns, rows)'' before using output functions. ''address'' is the **7-bit I²C address** of the LCD adapter module, ''columns'' is the number of characters per line, and ''rows'' is the number of lines. **The accepted argument range** is ''1~40'' columns and ''1~4'' rows. This does not mean that every LCD size has supported row addresses. In the current core, the start addresses of rows 3 and 4 are fixed at ''0x14'' and ''0x54'', which **do not match rows 3 and 4 of a 16 × 4 LCD.** ''IclcdBegin()'' returns ''false'' if the address, size, or device number is invalid, or if a required I²C transfer gets no response.

Every function returns success or failure as a ''bool''. To tell up to four LCDs apart, use ''device'' numbers ''0~3''. If omitted, the device number is ''0''. Each device must first be started with its own address using ''IclcdBegin(address, columns, rows, backlight, device)''. The default for ''backlight'' is ''true''.

^ Function ^ What it does ^
| [[:en-us_commands:reference:iclcdbegin|IclcdBegin(address, columns, rows, backlight, device)]] | Sets the LCD address, size, and initial backlight state, and checks the connection response. |
| [[:en-us_commands:reference:iclcdsetcursor|IclcdSetCursor(column, row, device)]] | Sets where the next character is written. Columns and rows start at **0**. Returns ''false'' outside the configured screen range. |
| [[:en-us_commands:reference:iclcdprint|IclcdPrint(value, ...)]] | Prints a string, character, integer, or real number. Examples: ''IclcdPrint(F("RUN"))'', ''IclcdPrint(12.34, 2)''. |
| [[:en-us_commands:reference:iclcdclear|IclcdClear(device)]] · [[:en-us_commands:reference:iclcdhome|IclcdHome(device)]] | ''IclcdClear()'' clears the screen and moves the cursor to the start. ''IclcdHome()'' moves only the cursor to the start and keeps the text. |
| [[:en-us_commands:reference:iclcdbacklight|IclcdBacklight(on, device)]] · [[:en-us_commands:reference:iclcddisplay|IclcdDisplay(on, device)]] | Turns the backlight or the display on or off. |
| [[:en-us_commands:reference:iclcdcursor|IclcdCursor(on, device)]] · [[:en-us_commands:reference:iclcdblink|IclcdBlink(on, device)]] | Controls the underline cursor and the blinking cursor. |
| [[:en-us_commands:reference:iclcdscrollleft|IclcdScrollLeft(device)]] · [[:en-us_commands:reference:iclcdscrollright|IclcdScrollRight(device)]] | Shifts the displayed content one position left or right. |
| [[:en-us_commands:reference:iclcdtextdirection|IclcdTextDirection(leftToRight, device)]] · [[:en-us_commands:reference:iclcdautoscroll|IclcdAutoscroll(on, device)]] | Sets the text entry direction and automatic shifting during entry. |
| [[:en-us_commands:reference:iclcdcreatechar|IclcdCreateChar(location, charmap, device)]] · [[:en-us_commands:reference:iclcdwrite|IclcdWrite(value, device)]] | Registers an 8-byte custom character at location ''0~7'', and prints one byte of character code. |
| [[:en-us_commands:reference:iclcdcommand|IclcdCommand(command, device)]] | An advanced function that sends an HD44780 command byte directly. |

In ''IclcdPrint()'', the second argument for a string is the device number. For an integer, the second argument is the base (''BIN'', ''OCT'', ''DEC'', ''HEX'', or ''2~36''). For a real number, it is the number of decimal places (''0~10''). In these two forms the device number is the **third argument**. For example, ''IclcdPrint("SUB", 1)'' writes a string to device 1, and ''IclcdPrint(255, HEX, 1)'' writes ''FF'' to device 1.

===== 3. Example: show text on the first and second lines =====

This example is for an **LCD with I²C address ''0x27'' and 20 columns × 4 rows**. If your LCD has a different address, replace ''0x27'' with the address you confirmed. For other screen sizes, check the row address limit above and the LCD documentation first, then change the column and row values. **Do not use this example on a 16 × 4 LCD.** In Arduino IDE, open **File → New Sketch**, paste the complete code, save it, then select **Verify (✓)** and **Upload (→)** in that order.

<code cpp>
void setup() {
  Serial.begin(115200);

  // Replace these with your LCD adapter's I²C address, columns, and rows.
  if (!IclcdBegin(0x27, 20, 4)) {  // Initialize the LCD and check the I²C response.
    Serial.println(F("LCD connection failed"));
    return;
  }

  IclcdSetCursor(0, 0);       // Move to the first position on line 1.
  IclcdPrint(F("ILOGICS"));   // Write text on line 1.
  IclcdSetCursor(0, 1);       // Move to the first position on line 2.
  IclcdPrint(F("LCD READY")); // Write text on line 2.
}

void loop() {
}
</code>

After uploading, check that ''ILOGICS'' appears on line 1 and ''LCD READY'' on line 2. If nothing appears, open the Arduino IDE **Serial Monitor at 115200 bps** and check whether ''LCD connection failed'' is printed. That message means you should check the address, wiring, power, or I²C response. ''true'' from ''IclcdBegin()'' means the I²C transfers got a response. It does not check whether characters are actually visible on the screen.

===== 4. If you do not know the I²C address =====

This sketch tries the address ranges of PCF8574 modules with ''IclcdBegin()'' and prints each address that responds. With the LCD connected, upload it and open the **Serial Monitor at 115200 bps**. Then enter the printed address in the example above. If only ''Done'' is printed, no module responded, so check the wiring and power. If ''Done'' does not appear either, restart the product with the Serial Monitor open.

<code cpp>
void setup() {
  Serial.begin(115200);
  delay(1000);

  for (uint8_t address = 0x20; address <= 0x3F; address++) {
    if (address == 0x28) address = 0x38;  // Skip the range PCF8574 modules do not use.
    if (IclcdBegin(address, 20, 4)) {
      Serial.print(F("Response at 0x"));
      Serial.println(address, HEX);
    }
  }
  Serial.println(F("Done"));
}

void loop() {
}
</code>

===== 5. If it does not work =====

^ Symptom ^ What to check, in order ^
| ''IclcdBegin'' cannot be found during Verify | Check that the ILOGICS Arduino SDK is installed and that the ILOGICS board for your product is selected in Arduino IDE. This example does not need a separate LCD library. |
| ''LCD connection failed'' on the Serial Monitor | Turn off the power and recheck the ''SDA'', ''SCL'', ''+5V'', and ''GND'' connections and the LCD module's power rating. ''0x27'' is an example, so confirm the actual module address and correct it. |
| No initialization error, but no text is visible | Check the LCD's contrast adjustment, backlight state, and actual number of columns and rows. Also check that the LCD-side connections of the PCF8574 adapter match the mapping these functions use. |
| ''IclcdSetCursor()'' or another function returns ''false'' | Check that ''IclcdBegin()'' succeeded for that device, that ''device'' is ''0~3'', and that the cursor's column and row are inside the configured screen range. |
| Errors when used with other I²C devices | Check for duplicate addresses. Also, do not run other ''Wire'' transfers or I²C slave callbacks while ''Iclcd...()'' is running. |

These functions use the PCF8574 connection **P0 = RS, P1 = R/W, P2 = Enable, P3 = backlight, P4~P7 = LCD D4~D7**. If your adapter module uses a different mapping, it may not display correctly even when the I²C address is right. ''IclcdCommand()'' changes the screen state directly, so use it only if you know HD44780 commands.

For the arguments and examples of each function, select its name in the table above. For product terminals and power ratings, your [[:en-us_products:mpino_series|MPINO]] or [[:en-us_products:mpaino|MPAINO]] product page takes priority.