i2c_interface_oled

Description

This project provides an interface using an OLED screen and navigation buttons for Raspberry Pi, using only the I2C port for communication. Pages are now configured in JSON files (config_lcd.json and custom.json), allowing easy customization and better readability.

Installation

Clone the project to the /opt/ directory:

cd /opt
git clone https://github.com/vampi62/i2c_interface_oled.git
sudo chmod 755 -R /opt/i2c_interface_oled
sudo chown root:root -R /opt/i2c_interface_oled

Run the installation script to set up the service:

sudo ./install_service.sh

If you ever need to uninstall the service, use the provided uninstall_service.sh script.

Configuration Guide

Configuration File Structure

The project now uses two JSON files for configuration:

• config_lcd.json: Configuration for main menu pages
• custom.json: Configuration for custom pages (special actions)

Creating a New Main Page

To add a new page to the main menu, modify the config_lcd.json file:

1. Add your page to the pages array:

{
  "pages": [
    [
      {"txt": "main menu", "destinationPage": 1},
      {"txt": "new page", "destinationPage": 2}
    ],
    [
      {"txt": "Item 1", "infoCommande": {"commande": "hostname -I"}},
      {"txt": "Item 2", "infoCommande": {"commande": "uptime"}}
    ],
    [
      {"txt": "Energy Status", "infoCommande": {"commande": "cat /sys/class/power_supply/BAT0/capacity"}},
      {"txt": "Usage", "infoCommande": {"commande": "vcgencmd measure_temp"}}
    ]
  ],
  "nav": [
    "menu",
    "menu/energy", 
    "menu/new_page"
  ]
}

Available Component Types

Navigation Button

{
  "txt": "Go to page 2",
  "destinationPage": 2
}

Information Display

{
  "txt": "IP :",
  "infoCommande": {
    "commande": "hostname -I | cut -d' ' -f1"
  }
}

Simple Action Button

{
  "txt": "Reboot",
  "actionCommande": {
    "commande": "sudo reboot"
  }
}

Toggle Button with Information and Action

{
  "txt": "Socket 1 :",
  "infoCommande": {
    "commande": "mosquitto_sub -h 192.168.5.1 -t zigbee2mqtt/power -C 1",
    "tag": "state_l1",
    "type": "json",
    "suffixe": ""
  },
  "actionCommande": {
    "commande": "mosquitto_pub -h 192.168.5.1 -t zigbee2mqtt/power/set -m ",
    "ifResult": [
      ["OFF", "\"{ \\\"state_l1\\\": \\\"ON\\\" }\""],
      ["ON", "\"{ \\\"state_l1\\\": \\\"OFF\\\" }\""]
    ]
  }
}

Custom Page Button

{
  "txt": "Network Test",
  "actionCommande": {
    "customPage": "network_test"
  }
}

Component Properties

Property	Required	Description
txt	Yes	Text displayed for the component
destinationPage	No	Destination page number
infoCommande	No	Configuration to retrieve data
actionCommande	No	Configuration to execute an action

infoCommande Configuration

Property	Required	Description
commande	Yes	Command to execute
type	No	Data type (json supported)
tag	No	JSON tag to extract (required if type = json)
suffixe	No	Suffix shown after the result
txtResultLiteral	No	Map literal results to custom texts

actionCommande Configuration

Property	Required	Description
commande	No	Command to execute
ifResult	No	Conditions based on infoCommande
customPage	No	Custom page name to launch

Creating a Custom Page

Custom pages are defined in custom.json and allow complex action sequences:

{
  "network_test": [
    {
      "nav": "Network Test",
      "txt": ["Ping Gateway", "In progress..."],
      "command": {
        "cmd": "ping -c 1 -W 2 192.168.1.1 > /dev/null && echo 0 || echo 1",
        "result": {"0": 1, "1": 2}
      }
    },
    {
      "nav": "Network Test",
      "txt": ["Ping Gateway", "Success"],
      "wait": 2,
      "exit": true
    },
    {
      "nav": "Network Test",
      "txt": ["Ping Gateway", "Failed"],
      "wait": 2,
      "exit": true
    }
  ]
}

Custom Page Properties

Property	Description
nav	Text displayed at the top of the page
txt	Array of texts (max 3 lines)
command.cmd	Command to execute
command.cwd	Working directory (optional)
command.result	Result → next page mapping
goto	Default next page
wait	Wait time in seconds
exit	true to exit the custom page

Practical Examples

Example 1: System Monitoring Page

[
  {
    "txt": "CPU  :",
    "infoCommande": {
      "commande": "top -bn1 | grep load | awk '{printf \"%.1f%%\", $(NF-2)*10}'"
    }
  },
  {
    "txt": "RAM  :",
    "infoCommande": {
      "commande": "free -m | awk 'NR==2{printf \"%s/%sMB\", $3,$2}'"
    }
  },
  {
    "txt": "TEMP :",
    "infoCommande": {
      "commande": "vcgencmd measure_temp | cut -b 6-12"
    }
  }
]

Example 2: IoT Control with MQTT

[
  {
    "txt": "Temp Sensor:",
    "infoCommande": {
      "commande": "mosquitto_sub -h 192.168.1.1 -t sensor/temp -C 1",
      "tag": "temperature",
      "type": "json",
      "suffixe": " °C"
    }
  },
  {
    "txt": "Light :",
    "infoCommande": {
      "commande": "mosquitto_sub -h 192.168.1.1 -t light/status -C 1",
      "tag": "state",
      "type": "json",
      "txtResultLiteral": [["true", "ON"], ["false", "OFF"]]
    },
    "actionCommande": {
      "commande": "mosquitto_pub -h 192.168.1.1 -t light/control -m ",
      "ifResult": [
        ["OFF", "\"true\""],
        ["ON", "\"false\""]
      ]
    }
  }
]

Validation Tools

Configuration Testing

Use the test script to validate your configurations:

python3 test_config.py

This script checks:

• Valid JSON syntax
• Configuration structures
• Consistent page references
• Testable commands

Configuration Loading

The config_loader.py module automatically handles:

• Detailed error messages
• Format error handling

Best Practices

JSON Structure

• Use 2-space indentation
• Name your custom pages explicitly
• Test your commands before integration

Security

• Avoid destructive commands without confirmation
• Use sudo only when necessary
• Limit timeouts for network commands

Performance

• Use optimized commands
• Limit frequent network calls
• Implement appropriate timeouts

Hardware Requirements

This project requires the following hardware components:

• 1 PCB (schematics available in resources)
• 1 3D-printed case (STL file available in resources)
• 1 OLED Display - I2C 128x64 Pixels, 0.96-inch, SSD1306 (Available on Amazon as a 5-pack)
• 1 PCF8574T (Available on Amazon as a 5-pack)
• 6 1K Ohm SMD resistors
• 4 SMT push buttons
• 2 Dupont connectors, 4x1 pin

Resources

• PCB Schematics: OshwLab PCB
• 3D Case STL File: Thingiverse STL File
• Compatible STL File: Thingiverse STL File
• Python Script: GitHub Repository

Example Display Images

Contributing

Contributions are welcome! Feel free to:

• Report bugs
• Suggest improvements
• Improve documentation
• Submit pull requests

License

This project is licensed - see the LICENSE file for details.