Skip to content

Commit 8fb0ce2

Browse files
MerzSebastianMerzSebastian
committed
update documentation
1 parent c632484 commit 8fb0ce2

File tree

3 files changed

+125
-48
lines changed

3 files changed

+125
-48
lines changed

‎README.md‎

Lines changed: 125 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -1,70 +1,147 @@
11
# OpenPLC Web Editor
22

3-
A visual programming interface for OpenPLC built with React and React Flow. This project allows users to create logic circuits using a block-based interface and generates bytecode for PLC controllers.
3+
A visual programming interface for Arduino controllers built with React and React Flow. This project allows users to create logic circuits using a block-based interface and generates optimized bytecode for Arduino microcontrollers.
44

5-
https://merzsebastian.github.io/OpenPLC/
5+
**Live Demo**: https://merzsebastian.github.io/OpenPLC/
66

7-
License: CC BY-NC 4.0
7+
**License**: CC BY-NC 4.0
88

99
## Current Status
1010

11-
Thrown together weekend project. May continou updating it once in a while :)
12-
Needs some cleanup and structuring. also its my first react project so best pracitces are not found here
11+
Weekend project with occasional updates. This is my first React project, so best practices may not always be followed.
1312

13+
## Features
1414

15-
### Current Features:
16-
- Drag-and-drop block interface
17-
- Support for digital I/O blocks (only tested with digital pins, analog pins may still be broken)
18-
- Logic gates (AND, OR, NOT) with configurable inputs
15+
- Drag-and-drop block interface for Arduino programming
16+
- Support for digital I/O blocks with Arduino pin mapping
17+
- Logic gates (AND, OR, NOT, NAND, NOR, XOR) with configurable inputs
1918
- SR Latch block with configurable initial state
20-
- Pulse block with pulse length and interval settings
19+
- Pulse generator with adjustable timing
20+
- Toggle block for edge-triggered toggling
2121
- Project save/load functionality
22-
- Bytecode generation for Arduino-compatible controllers
22+
- Bytecode generation optimized for Arduino
23+
- WebSerial integration for direct programming of Arduino devices
24+
- EEPROM storage on Arduino for program persistence
2325

24-
## Flash Functionality
26+
## Quick Start Guide
2527

26-
The "Flash" button currently prints the generated bytecode to the browser console. Future implementation will include WebSerial integration for direct programming of devices via the browser.
28+
### Using the Web Interface
29+
30+
1. **Add components**: Drag blocks from the left sidebar to the canvas
31+
2. **Configure components**: Click on components to set Arduino pins and parameters
32+
3. **Connect components**: Drag from output handles to input handles
33+
4. **Generate and deploy code**:
34+
- Click **"Copy for Wokwi"** to get code for simulation (paste into Wokwi)
35+
- Click **"Upload via WebSerial"** to send directly to Arduino hardware
36+
37+
### For Physical Arduino Hardware
38+
39+
1. **Load the Arduino code**:
40+
- Copy the custom Arduino code from this project via the "Copy Arduino Code" button
41+
- Paste it into the Arduino IDE
42+
- Upload it to your Arduino board
43+
44+
2. **Upload your logic**:
45+
- Design your circuit in the web interface
46+
- Click "Upload via WebSerial"
47+
- Select your Arduino when prompted by the browser
48+
- The program will upload and run automatically
49+
50+
### For Wokwi Simulation
51+
52+
1. **Design your circuit** in the web interface
53+
2. Click **"Copy for Wokwi"** to generate the bytecode
54+
3. In Wokwi, paste the bytecode into the Arduino code section
55+
4. Add `#define WOKWI` at the top of your Wokwi sketch
56+
5. Run the simulation to test your logic
57+
58+
## Arduino Code Integration
59+
60+
This project includes custom Arduino code that implements:
61+
- Bytecode interpreter for efficient execution
62+
- WebSerial communication protocol
63+
- EEPROM storage for program persistence
64+
- Support for all logic operations and timers
65+
66+
The Arduino code is specifically optimized for:
67+
- Arduino Nano 328P (tested platform)
68+
- Efficient execution with minimal memory footprint
69+
- Persistent storage across power cycles
70+
71+
## Bytecode Structure
72+
73+
The system uses a compact bytecode format optimized for Arduino:
74+
75+
```
76+
[START_BYTE][LENGTH][DATA...][CHECKSUM]
77+
```
78+
79+
- **START_BYTE**: 0x7E (marks message beginning)
80+
- **LENGTH**: Number of bytes in DATA section
81+
- **DATA**: Optimized bytecode instructions
82+
- **CHECKSUM**: Sum of DATA bytes modulo 256 for verification
2783

2884
## Opcode Reference
2985

30-
| Opcode | Name | Parameters | Description |
31-
|--------|------|------------|-------------|
32-
| 1 | SET_PIN_MODE_INPUT | pin (1 byte) | Set pin as input |
33-
| 2 | SET_PIN_MODE_OUTPUT | pin (1 byte) | Set pin as output |
34-
| 3 | READ_PIN | pin (1 byte), varIndex (1 byte) | Read digital pin to variable |
35-
| 4 | WRITE_PIN | pin (1 byte), varIndex (1 byte) | Write variable to digital pin |
36-
| 5 | READ_ANALOG_PIN | pin (1 byte), varIndex (1 byte) | Read analog pin to variable |
37-
| 6 | WRITE_ANALOG_PIN | pin (1 byte), varIndex (1 byte) | Write variable to analog pin (PWM) |
38-
| 10 | NOT | inputVar (1 byte), outputVar (1 byte) | Logical NOT operation |
39-
| 11 | AND | numInputs (1 byte), inputs (n bytes), outputVar (1 byte) | Logical AND with variable inputs |
40-
| 12 | OR | numInputs (1 byte), inputs (n bytes), outputVar (1 byte) | Logical OR with variable inputs |
41-
| 13 | NAND | numInputs (1 byte), inputs (n bytes), outputVar (1 byte) | Logical NAND with variable inputs |
42-
| 14 | NOR | numInputs (1 byte), inputs (n bytes), outputVar (1 byte) | Logical NOR with variable inputs |
43-
| 15 | XOR | numInputs (1 byte), inputs (n bytes), outputVar (1 byte) | Logical XOR with variable inputs |
44-
| 16 | LATCH | setVar (1 byte), resetVar (1 byte), outputVar (1 byte), initialState (1 byte) | SR Latch implementation |
45-
| 17 | PULSE | outputVar (1 byte), pulseLength (2 bytes), interval (2 bytes) | Timer with configurable pulse and interval |
46-
| 30 | DELAY | delayTime (1 byte) | Delay execution (delayTime × 10ms) |
86+
| Opcode | Instruction | Parameters | Description |
87+
|--------|-------------|------------|-------------|
88+
| 1 | SET_PIN_MODE_INPUT | pin | Set Arduino pin as input |
89+
| 2 | SET_PIN_MODE_OUTPUT | pin | Set Arduino pin as output |
90+
| 3 | READ_PIN | pin, var_index | Read digital pin to variable |
91+
| 4 | WRITE_PIN | pin, var_index | Write variable to digital pin |
92+
| 5 | READ_ANALOG_PIN | pin, var_index | Read analog pin to variable |
93+
| 6 | WRITE_ANALOG_PIN | pin, var_index | Write variable to analog pin (PWM) |
94+
| 10 | NOT | input_var, output_var | Logical NOT operation |
95+
| 11 | AND | num_inputs, inputs..., output_var | Logical AND operation |
96+
| 12 | OR | num_inputs, inputs..., output_var | Logical OR operation |
97+
| 13 | NAND | num_inputs, inputs..., output_var | Logical NAND operation |
98+
| 14 | NOR | num_inputs, inputs..., output_var | Logical NOR operation |
99+
| 15 | XOR | num_inputs, inputs..., output_var | Logical XOR operation |
100+
| 16 | LATCH | set_var, reset_var, output_var, initial_state | SR Latch implementation |
101+
| 17 | PULSE | output_var, pulse_ms, interval_ms | Pulse generator |
102+
| 18 | TOGGLE | input_var, output_var, initial_state | Toggle on rising edge |
47103

48-
## Future Plans
104+
## Troubleshooting
105+
106+
### WebSerial Issues
107+
- Use Chrome or Edge for best WebSerial support
108+
- Ensure no other serial monitors are connected to the Arduino
109+
- Disconnect components from pins 0 and 1 (RX/TX) during upload
110+
- If upload fails, try manually resetting the Arduino just before uploading
111+
112+
### Program Not Running
113+
- Verify your Arduino has the correct custom code uploaded
114+
- Check that the EEPROM signature is valid
115+
- Ensure you're not using the serial port for debugging while running
116+
117+
## Development
118+
119+
This project was bootstrapped with [Create React App](https://github.com/facebook/create-react-app).
49120

50-
- WebSerial integration for direct device programming
51-
- Improved timer precision with extended range
52-
- Support for different time units (ms, seconds, hours)
53-
- Connection validation rules
54-
- Analog input support with threshold conversion blocks
55-
- Additional logic blocks and functionality
121+
### Available Scripts
56122

57-
## Getting Started
123+
#### `npm start`
124+
Runs the app in development mode at [http://localhost:3000](http://localhost:3000)
125+
126+
#### `npm test`
127+
Launches the test runner in interactive watch mode
128+
129+
#### `npm run build`
130+
Builds the app for production to the `build` folder
131+
132+
#### `npm run eject`
133+
**Note: this is a one-way operation.** Ejects from Create React App
134+
135+
## Future Plans
58136

59-
### Prerequisites
60-
- Node.js (v14 or higher)
61-
- npm or yarn
137+
- Support for more Arduino board types
138+
- Expanded library of logic blocks
139+
- Real-time serial monitoring
140+
- Enhanced simulation capabilities
62141

63-
### Installation
64-
1. go into frontend folder: `cd logic-editor`
65-
2. Install dependencies: `npm install`
66-
3. Start the development server: `npm start`
67-
4. Open your browser to `http://localhost:3000`
142+
## Learn More
68143

69-
### Building for Production
70-
Run `npm run build` to create a production build.
144+
- [React Documentation](https://reactjs.org/)
145+
- [WebSerial API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Serial_API)
146+
- [Arduino Reference](https://www.arduino.cc/reference/en/)
147+
- [Wokwi Simulator](https://wokwi.com/)

‎documentation/ui.png‎

183 KB
Loading

‎project.zip‎

-6.15 KB
Binary file not shown.

0 commit comments

Comments
 (0)