PiPLC File Formats¶

PiPLC uses several file formats for project persistence, configuration, and data exchange.

Project File (.plcproj)¶

XML format with versioned schema for single-context ladder programs.

Current version: 3.2

<?xml version="1.0" encoding="UTF-8"?>
<PLCProject version="3.2">
  <Metadata>
    <Name>ProjectName</Name>
  </Metadata>
  <SymbolTable>
    <Symbol name="StartButton" type="BOOL" address="I:0/0" />
  </SymbolTable>
  <Programs>
    <Program name="Main" type="Main">
      <Rungs>
        <Rung id="0">
          <Instruction type="XIC" address="I:0/0" column="0" />
          <Instruction type="OTE" address="O:0/0" column="10" />
        </Rung>
      </Rungs>
    </Program>
  </Programs>
  <WatchList>
    <WatchEntry address="I:0/0" />
  </WatchList>
  <RemoteConnection>
    <Host>192.168.1.50</Host>
    <Port>9100</Port>
    <ContextId>uuid-here</ContextId>
    <ContextName>PLC1</ContextName>
  </RemoteConnection>
  <HmiFile>panel.hmi</HmiFile>
</PLCProject>

See Schema Documentation for the full element and attribute reference, and Versioning Strategy for migration rules.

Schema Version History¶

Version	Changes
2.0	Initial schema with basic instructions
3.0	Added Branch/RungPath for parallel branches
3.1	Added decorator serialization for contacts
3.2	Added watch list serialization, remote connection metadata, HMI file path

Optional Elements¶

Element	Description
`<WatchList>`	Saved watch panel entries (added in v3.2)
`<RemoteConnection>`	Saved remote engine connection info for auto-reconnect on project open
`<HmiFile>`	Path to an `.hmi` file that auto-opens with the project

Multi-PLC Project File (.mplcproj)¶

XML format that serializes an entire multi-context workspace. Each <Context> embeds a full <PLCProject> document. Signal routes are persisted alongside contexts.

<?xml version="1.0" encoding="UTF-8"?>
<MultiPLCProject version="1.0">
  <Contexts activeContext="uuid-of-active">
    <Context id="uuid-1" name="PLC1">
      <FilePath>C:/Projects/plc1.plcproj</FilePath>
      <Program>
        <PLCProject version="3.2">
          <!-- Full embedded project -->
        </PLCProject>
      </Program>
    </Context>
  </Contexts>

  <SignalRouter enabled="true">
    <Route id="route-uuid" enabled="true">
      <SourceContext>PLC1</SourceContext>
      <SourceAddress>B:0/0</SourceAddress>
      <DestContext>PLC2</DestContext>
      <DestAddress>B:0/0</DestAddress>
      <DataType>Bit</DataType>
      <IntervalMs>50</IntervalMs>
      <Description>Link output to input</Description>
    </Route>
  </SignalRouter>
</MultiPLCProject>

Contexts with no program omit the <Program> element. Programs are NOT auto-downloaded on load — users must download manually.

HMI Project File (.hmi)¶

XML format for HMI panel designs. Contains element layout, property bindings, and canvas settings.

<?xml version="1.0" encoding="UTF-8"?>
<HmiProject>
  <Canvas width="800" height="480" backgroundColor="#2b2b2b"
          gridSpacing="20" gridColor="#80ffffff" />
  <Elements>
    <Element type="PushButton" id="btn-1">
      <Property name="x" value="100" />
      <Property name="y" value="200" />
      <Property name="width" value="80" />
      <Property name="height" value="40" />
      <Property name="label" value="Start" />
      <Property name="address" value="I:0/0" />
    </Element>
    <!-- Additional elements... -->
  </Elements>
</HmiProject>

Canvas Properties¶

Property	Description
`width` / `height`	Target canvas resolution in pixels
`backgroundColor`	Canvas background color (hex)
`gridSpacing`	Grid cell size in pixels
`gridColor`	Grid line color (hex with optional alpha)

Element Types¶

`type` Value	Element
`PushButton`	Momentary push button
`ToggleSwitch`	ON/OFF toggle switch
`SelectorSwitch`	Multi-position selector
`Slider`	Analog slider control
`NumericEntry`	Direct numeric input
`IndicatorLamp`	Color-coded status indicator
`MotorIndicator`	Motor state display
`NumericDisplay`	Numeric value readout
`BarGraph`	Visual bar chart
`Trend`	Time-series trend chart
`TextLabel`	Static text label
`Rectangle`	Decorative rectangle
`BackgroundImage`	Background image layer

On Windows, .hmi files are associated with PiPLC-HMI during installation. On Linux, a MIME type and desktop entry are registered.

Symbol Table CSV¶

Standard 5-column CSV format for bulk symbol import/export. Compatible with spreadsheet editors.

Symbol Name,Data Type,Address,Initial Value,Description
StartButton,BOOL,I:0/0,0,Main start pushbutton
Counter1,COUNTER,C:0,,Production counter

Import/export is available in the Symbol Table Dialog and via SymbolTableCSV utility class.

I/O Configuration (.ioconfig)¶

JSON format for I/O provider configuration. Independent of project files so the same ladder program can run with different hardware configurations.

{
    "version": 1,
    "provider": "gpio",
    "gpioChip": "/dev/gpiochip0",
    "digitalPins": [
        {
            "gpioLine": 17,
            "direction": "input",
            "activeLow": false,
            "bias": "pull_down",
            "plcWord": 0,
            "plcBit": 0,
            "label": "Start Button"
        },
        {
            "gpioLine": 22,
            "direction": "output",
            "activeLow": false,
            "bias": "disabled",
            "plcWord": 0,
            "plcBit": 0,
            "label": "Motor Relay"
        }
    ],
    "analogChannels": [
        {
            "channel": 0,
            "direction": "input",
            "plcNWord": 10,
            "rawMin": 0,
            "rawMax": 32767,
            "scaledMin": 0,
            "scaledMax": 10000,
            "label": "Temperature Sensor"
        }
    ],
    "virtualFallback": {
        "inputCount": 8,
        "outputCount": 8
    }
}

Supported Providers¶

`provider` value	Provider	Notes
`"virtual"`	Virtual I/O	In-memory simulation. Uses `virtualFallback` counts.
`"gpio"`	GPIO provider	Generic libgpiod-based mapping via `digitalPins` and `analogChannels`.
`"explorer_hat_pro"`	Explorer HAT Pro provider	Fixed hardware mapping. No pin table required.
`"modbus_tcp_client"`	Modbus TCP Client provider	Uses `modbusClient` block for host/port/register mappings.
`"composite"`	Composite I/O provider	Uses `children` array with per-provider configurations.

Composite Provider Configuration¶

The composite provider wraps multiple child providers into a single unified I/O layer:

{
    "version": 1,
    "provider": "composite",
    "children": [
        {
            "provider": "gpio",
            "gpioChip": "/dev/gpiochip0",
            "digitalPins": [ ... ]
        },
        {
            "provider": "modbus_tcp_client",
            "modbusClient": { ... }
        }
    ]
}

Each child provider claims specific PLC addresses. Address conflicts between children are rejected on load.

Configuration Fields¶

Field	Description
`provider`	`"virtual"`, `"gpio"`, `"explorer_hat_pro"`, `"modbus_tcp_client"`, or `"composite"`
`boardName`	Optional board descriptor name for GPIO mapping (preferred in UI-generated files)
`gpioChip`	libgpiod chip device path (e.g., `/dev/gpiochip0`)
`digitalPins[].gpioLine`	GPIO line number on the chip
`digitalPins[].direction`	`"input"` or `"output"`
`digitalPins[].activeLow`	Invert logic level
`digitalPins[].bias`	`"disabled"`, `"pull_up"`, or `"pull_down"`
`digitalPins[].plcWord`	PLC address word (I:word/bit or O:word/bit)
`digitalPins[].plcBit`	PLC address bit
`analogChannels[].channel`	ADC/DAC channel number
`analogChannels[].plcNWord`	N: region word index
`analogChannels[].rawMin/rawMax`	Raw ADC/DAC range
`analogChannels[].scaledMin/scaledMax`	Scaled engineering units range
`virtualFallback`	Input/output counts when provider is `"virtual"`
`children`	Array of child provider configurations (composite provider only)
`modbusClient.host`	Modbus server hostname or IP
`modbusClient.port`	Modbus TCP port (1-65535, default 502)
`modbusClient.unitId`	Modbus unit/slave ID (1-247)
`modbusClient.timeoutMs`	Poll timeout in milliseconds
`modbusClient.pollIntervalMs`	Poll interval in milliseconds
`modbusClient.discreteInputMappings[]`	FC02 discrete input -> `I:` mapping entries (`modbusAddr`, `plcWord`, `plcBit`)
`modbusClient.coilMappings[]`	`O:` <-> FC01/05/15 coil mapping entries (`modbusAddr`, `plcWord`, `plcBit`)
`modbusClient.inputRegisterMappings[]`	FC04 input register -> `N:` mapping entries (`modbusAddr`, `plcNWord`)
`modbusClient.holdingRegisterMappings[]`	`N:` <-> FC03/06/16 holding register mappings (`modbusAddr`, `plcNWord`)

Provider-Specific Minimal Examples¶

{ "version": 1, "provider": "virtual", "virtualFallback": { "inputCount": 8, "outputCount": 8 } }

{ "version": 1, "provider": "explorer_hat_pro" }

{
  "version": 1,
  "provider": "modbus_tcp_client",
  "modbusClient": {
    "host": "192.168.1.100",
    "port": 502,
    "unitId": 1,
    "timeoutMs": 1000,
    "pollIntervalMs": 100,
    "discreteInputMappings": [],
    "coilMappings": [],
    "inputRegisterMappings": [],
    "holdingRegisterMappings": []
  }
}

I/O Config CSV¶

The IOConfigPanel also supports a section-based CSV format for bulk editing:

[DigitalPins]
gpioLine,direction,activeLow,bias,plcWord,plcBit,label
17,Input,false,PullDown,0,0,Start Button
22,Output,false,Disabled,0,0,Motor Relay

[AnalogChannels]
channel,direction,plcNWord,rawMin,rawMax,scaledMin,scaledMax,label
0,Input,10,0,4095,0,10000,Temperature Sensor