opencplc 0.1.0__tar.gz

opencplc-0.1.0/PKG-INFO

@@ -0,0 +1,251 @@
+Metadata-Version: 2.4
+Name: opencplc
+Version: 0.1.0
+Summary: Project configuration and build tool for OpenCPLC
+Author: Xaeian
+License: MIT
+Project-URL: Repository, https://github.com/OpenCPLC/Forge
+Keywords: embedded,stm32,opencplc,build,forge
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+## OpenCPLC ⚒️ Forge
+
+**Forge** is a console app that makes working with **OpenCPLC** easier. Its job is to set up your environment so you 👨‍💻developer can focus on building apps instead of fighting with configs and compilation. Available as a **Python [`pip`](https://pypi.org/project/opencplc)** package or standalone **`opencplc.exe`** from 🚀[Releases](https://github.com/OpenCPLC/Forge/releases) _(in that case add its location to system **PATH** manually)_
+
+```bash
+pip install opencplc
+```
+
+Just pick a folder _(your workspace)_ open [CMD](#-console) and type:
+
+```bash
+opencplc -n <project_name> -b <board>
+opencplc -n myapp -b Uno
+```
+
+This creates a directory _(or directory tree)_ in [projects location](#️-config) `${projects}` matching the name `<project_name>`. Two files are created inside: `main.c` and `main.h`: the minimal project setup. Don't delete them or move to subfolders.
+
+When you have more projects, you can switch between them freely:
+
+```bash
+opencplc <project_name>
+opencplc myapp
+```
+
+You can also pick projects by number from list:
+
+```bash
+opencplc -l  # show project list
+opencplc 3   # load project #3 from list
+```
+
+When creating new project or switching to existing one, all files needed for compilation _(`makefile`, `flash.ld`, ...)_ are regenerated. These transform everything _(project and framework files: `.c`, `.h`, `.s`)_ into binary files `.bin`/`.hex` that can be flashed to the PLC.
+
+If you change `PRO_x` config values in **`main.h`** or modify **project structure**:
+
+- adding new files,
+- moving files,
+- deleting files,
+- renaming files,
+
+you need to reload the project. If project is already active, no need to type its name `-r --reload`:
+
+```bash
+opencplc <project_name>
+opencplc -r
+```
+
+Here _(roughly)_ ends **Forge** job, and further work goes like typical **embedded systems** project using [**✨Make**](#-make).
+
+## ✨ Make
+
+If you have proper project config and `makefile` generated by ⚒️**Forge**, to build and flash program to PLC just open console in workspace and type:
+
+```bash
+make build  # build C project to binary
+make flash  # upload binary to PLC memory
+# or
+make run    # run = build + flash
+```
+
+`makefile` has few more functions. Full list:
+
+- **`make build`** or just **`make`**: Builds C project to `.bin`, `.hex`, `.elf` files
+- **`make flash`**: Uploads program to PLC _(microcontroller)_ memory
+- **`make run`**: Does `make build`, then `make flash`
+- **`make clean`** or `make clr`: Removes built files for active project
+- `make clean_all` or `make clr_all`: Removes built files for all projects
+- `make dist`: Copies `.bin` and `.hex` files to the project folder
+- **`make erase`**: Completely wipes microcontroller memory _(**erase** full chip)_
+
+## ⚙️ Config
+
+On first run ⚒️Forge creates config file **`opencplc.json`**. It contains:
+
+- **`version`**: Default OpenCPLC framework version. This version gets installed. Replaces unspecified `-f --framework`. Value `latest` means newest stable version.
+- `paths`: List of _(relative)_ paths
+  - `projects`: Main projects directory. New projects go here. You can also copy projects manually. All projects are detected automatically. Project name is the path after this location.
+  - `examples`: Directory with demo examples downloaded from [Demo](https://github.com/OpenCPLC/Demo) repository.
+  - `framework`: Directory with all OpenCPLC framework versions. Subdirectories are created for versions like `major.minor.patch`, `develop` or `main`. Each contains files for that framework version. Only needed versions are downloaded.
+  - `build`: Directory with built applications
+- `default`: Default values _(`chip`, `flash`, `ram`, `optLevel`)_ for params not passed when creating new project
+- **`pwsh`**: Setting this to `true` makes `makefile` for **PowerShell**. For `false` it's **Bash** version.
+- `available-versions`: List of all available framework versions. Set automatically.
+
+## 🤔 How works?
+
+First **Forge** installs **GNU Arm Embedded Toolchain**, **OpenOCD**, **Make**, **Git** client and sets system variables if these apps aren't visible from console. For HOST platform, **MinGW** (GCC for Windows) is installed instead of ARM toolchain. If you don't want anyone messing with your system, you can [set it up manually](self-install.md). When ⚒️**Forge** installs missing apps, it asks to reset console because system variables load on startup and new ones were added.
+
+Then if needed, it clones OpenCPLC framework from [repository](https://github.com/OpenCPLC/Core) to `${framework}` folder from `opencplc.json`. Version from config or specified with `-f --framework` gets cloned:
+
+```bash
+opencplc <project_name> --new -f 1.0.2
+opencplc <project_name> --new -f develop
+```
+
+### 📌 Project versioning
+
+Each project stores in `main.h` the framework version it was created with _(definition `PRO_VERSION`)_. When switching to existing project:
+
+- If project version differs from current framework, **Forge** tries to download matching version
+- If download fails, warning about potential incompatibility shows up
+- Demo examples `-e --example` always use version saved in project
+
+This way old projects can compile even after framework update to newer version.
+
+Main **Forge** function is preparing files needed for project:
+
+- `flash.ld`: defines RAM and FLASH memory layout _(overwrites, STM32 only)_
+- `makefile`: Contains build, clean and flash rules _(overwrites)_
+- `c_cpp_properties.json`: sets header paths and IntelliSense config in VS Code _(overwrites)_
+- `launch.json`: configures debugging in VSCode _(overwrites)_
+- `tasks.json`: describes tasks like compile or flash _(overwrites)_
+- `settings.json`: sets local editor preferences _(creates once, not overwritten)_
+- `extensions.json`: suggests useful VSCode extensions _(creates once, not overwritten)_
+
+There's also bunch of helper functions accessible through smart use of [**🚩flags**](#-flags).
+
+### 🗂️ Workspace structure
+
+```
+workspace/
+├─ opencplc.json  # workspace config
+├─ makefile       # active project (generated by Forge)
+├─ flash.ld       # linker script (generated by Forge, STM32 only)
+├─ .vscode/       # VSCode config (generated by Forge)
+├─ opencplc/      # framework (downloaded automatically)
+│  ├─ 1.0.3/
+│  ├─ 1.2.0/
+│  └─ develop/
+├─ projects/      # user projects
+│  ├─ myapp/
+│  │  ├─ main.c
+│  │  └─ main.h
+│  └─ firm/app/   # projects can be nested
+│     ├─ main.c
+│     └─ main.h
+├─ examples/      # demo examples
+└─ build/         # compiled binary files
+```
+
+If IntelliSense stops working, use `F1` → _C/C++: Reset IntelliSense Database_.
+
+## 🖥️ Host
+
+Forge supports **Host** platform for developing and testing code on PC (Windows/Linux) without embedded hardware:
+
+```bash
+opencplc -n myapp -c Host  # desktop project
+```
+
+This creates project that compiles with native GCC (MinGW on Windows) instead of ARM toolchain. Useful for:
+
+- Testing algorithms and logic without hardware
+- Developing protocol parsers and data processing
+- Unit testing framework components
+- Quick prototyping before deploying to PLC
+
+Host platform provides stub implementations for hardware-dependent modules (GPIO, timers, etc.) so code structure remains compatible with STM32 targets.
+
+## 🚩 Flags
+
+Beyond the basic flags described above, there are a few more worth knowing. Full list:
+
+#### Basic
+
+- **`name`**: Project name. Default first argument. Also defines the project path: `${projects}/name`, and output files (`.bin`, `.hex`, `.elf`) are tied to it. Can also be a project number from the `-l` list.
+- `-n --new`: Creates a new project with the given name.
+- `-e --example`: Loads a demo example by name from the [Demo](https://github.com/OpenCPLC/Demo) repository.
+- `-r --reload`: Reads the project name and example flag from an existing `makefile`, then regenerates project files. **`name`** is not required.
+- `-d --delete`: Deletes the project with the given **`name`**.
+- `-g --get`: Downloads a project from Git (**GitHub**, **GitLab**, ...) or a remote ZIP and adds it as a new project. The second argument (first is the link) can be a reference (`branch`, `tag`). If **`name`** is not specified, it tries to read it from the `@name` field in `main.h`.
+
+#### Hardware config
+
+- `-b --board`: PLC board for the new project: `Uno`, `Dio`, `Aio`, `Eco`, `Custom` for a custom design, or `None` for a bare microcontroller. `Custom` provides the PLC layer without peripheral mapping — fill it in manually.
+- `-c --chip`: Microcontroller or platform: `STM32G081`, `STM32G0C1`, `STM32WB55`, `HOST` (compile for PC). Without `-b --board`, the project runs without the PLC layer — only HAL and standard framework libraries. Useful for Nucleo boards or custom hardware.
+- `-m --memory`: Memory in kB: `FLASH RAM [RESERVED]`. `RESERVED` is the memory allocated for config and EEPROM, subtracted from FLASH in the linker file `flash.ld`. _(STM32 only)_
+
+#### Build config
+
+- `-f --framework`: Framework version: `latest`, `develop`, `1.0.0`. If not provided, read from the `version` field in `opencplc.json`.
+- `-o --opt-level`: Compiler optimization level: `O0` _(debug)_, `Og` _(default)_, `O1`, `O2`, `O3`. Levels `O2` and `O3` show a warning for STM32 _(timing/debugging issues)_ but are allowed for `HOST`.
+
+#### Info
+
+- `-l --list`: Lists existing projects, or examples when `-e --example` is active.
+- `-i --info`: Returns basic info about the specified or active project, including project and framework versions.
+- `-F --framework-versions`: Lists all available OpenCPLC framework versions.
+- `-v --version`: Shows the ⚒️Forge version and repository link.
+
+#### Tools
+
+- `-a --assets`: Downloads helper materials for design _(docs, diagrams)_. Optionally accepts a folder name as destination.
+- `-u --update`: Checks for and installs ⚒️Forge updates. Accepts a specific version or `latest`.
+- `-y --yes`: Auto-confirms all prompts _(non-interactive mode)_.
+
+#### Hash utilities
+
+- `-hl --hash-list`: Generates an enum with DJB2 hashes from a tag list.
+- `-ht --hash-title`: Enum type name for the hash generator.
+- `-hd --hash-define`: Uses `#define` instead of `enum` for hash output.
+
+🗑️ Deleting and 💾 copying projects can be done directly from the OS.
+Each project stores all the information it needs in `main.h`, and its presence is auto-detected on startup.
+
+## 📟 Console
+
+⚒️Forge and ✨Make are console programs. Essential for working with OpenCPLC.
+
+System console is available in many apps like **Command Prompt**, **PowerShell**, [**GIT Bash**](https://git-scm.com/downloads), even terminal in [**VSCode**](https://code.visualstudio.com/). If console call returns error, it probably wasn't opened in workspace. Close console and open it in right folder or navigate manually with `cd` command.
+
+## 📋 Usage examples
+
+```bash
+# Creating new project
+opencplc -n myapp -b Uno                  # project for OpenCPLC Uno board
+opencplc -n myapp -b Eco -m 128 36        # project for Eco with 128kB/36kB memory
+opencplc -n myapp -b Custom -c STM32G081  # custom hardware with PLC layer (no peripheral mapping)
+opencplc -n myapp -c STM32G081            # bare-metal project for STM32G081 (e.g. Nucleo)
+opencplc -n myapp -c Host                 # desktop project (Windows/Linux)
+
+# Managing projects
+opencplc myapp      # load project 'myapp'
+opencplc 3          # load project #3 from list
+opencplc -r         # reload active project
+opencplc -l         # list all projects
+opencplc -i         # info about active project
+
+# Demo examples
+opencplc -e blinky  # load example 'blinky'
+opencplc -e -l      # list available examples
+
+# Downloading projects
+opencplc -g https://github.com/user/repo
+opencplc -g https://github.com/user/repo v1.0.0
+
+# Updates
+opencplc -u         # update Forge to latest version
+opencplc -F         # show available Core versions
+```

opencplc-0.1.0/opencplc/__init__.py

@@ -0,0 +1,13 @@
+# opencplc/__init__.py
+
+from .config import VER
+
+__version__ = VER
+__repo__ = "OpenCPLC/Forge"
+__python__ = ">=3.12"
+__description__ = "Project configuration and build tool for OpenCPLC"
+__author__ = "Xaeian"
+__keywords__ = ["embedded", "stm32", "opencplc", "build", "forge"]
+__scripts__ = {
+  "opencplc": "opencplc.__main__:main",
+}

opencplc-0.1.0/opencplc/__main__.py

@@ -0,0 +1,378 @@
+# opencplc/__main__.py
+
+import signal, sys
+from xaeian import Print, Color as c, Ico, FILE, DIR, JSON, PATH, replace_end
+from .config import VER, URL_FTP, URL_CORE, URL_FORGE, URL_DEMO
+from .args import flag, load_args, check_flags
+from .platforms import resolve_chip
+from .templates import load_templates
+from .project import generate_project
+from . import utils
+
+p = Print()
+
+def handle_sigint(signum, frame):
+  p.wrn(f"Closing {c.GREY}(Ctrl+C){c.END}...")
+  sys.exit(0)
+
+signal.signal(signal.SIGINT, handle_sigint)
+
+def load_lines(path:str) -> list[str]:
+  try: return [ln.rstrip('\n\r') for ln in FILE.load_lines(path)]
+  except Exception: return []
+
+def main():
+  templates = load_templates()
+  # Load opencplc.json
+  forge_cfg = JSON.load("opencplc.json", templates["opencplc.json"])
+  missing = utils.find_missing_keys(templates["opencplc.json"], forge_cfg)
+  if missing:
+    p.err(f"Missing key {c.BLUE}{missing[0]}{c.END} in {c.ORANGE}opencplc.json{c.END}")
+    sys.exit(1)
+  # Check available versions
+  versions = utils.git_get_refs(URL_CORE, "--ref", use_git=True)
+  if versions:
+    forge_cfg["available-versions"] = versions
+  else:
+    p.wrn(f"No internet access or {c.BLUE}GitHub{c.END} is not responding")
+    if "available-versions" not in forge_cfg:
+      p.err("First run requires network access to fetch available framework versions")
+      sys.exit(1)
+  JSON.save_pretty("opencplc.json", forge_cfg)
+  forge_cfg["version"] = utils.version_real(forge_cfg["version"], forge_cfg["available-versions"][0])
+  # Parse arguments
+  args = load_args()
+  # Print-only actions
+  exit_flag = False
+  if args.version:
+    p.inf(f"OpenCPLC Forge {c.BLUE}{VER}{c.END}")
+    p.gap(utils.color_url("https://github.com/OpenCPLC/Forge"))
+    exit_flag = True
+  if args.framework_versions:
+    latest = f" {c.GREY}(latest){c.END}"
+    msg = "Framework Versions: "
+    color = c.BLUE
+    for ver in forge_cfg["available-versions"]:
+      msg += f"{color}{ver}{c.END}{latest}, "
+      color, latest = c.CYAN, ""
+    print(msg.rstrip(", "))
+    exit_flag = True
+  if args.hash_list:
+    print(utils.c_code_enum(args.hash_list, args.hash_title, args.hash_define))
+    exit_flag = True
+  if args.update:
+    new_ver = args.update in ("last", "latest")
+    versions = utils.git_get_refs(URL_FORGE, "--tags", use_git=True)
+    if not versions:
+      p.err(f"No access to {c.BLUE}GitHub{c.END}")
+      sys.exit(1)
+    target = utils.version_real(args.update, versions[0])
+    if target != VER:
+      p.inf(f"Installed: {c.ORANGE}{VER}{c.END}")
+      p.inf(f"{'Latest' if new_ver else 'Target'}: {c.BLUE}{target}{c.END}")
+      p.run(f"{'Update' if new_ver else 'Replace'} required")
+      utils.install("forge.exe", f"{URL_FORGE}/releases/download/{target}", ".", args.yes, False)
+    else:
+      p.ok(f"Forge is at {'latest' if new_ver else 'target'} version {c.BLUE}{VER}{c.END}")
+    exit_flag = True
+  if args.assets:
+    DIR.ensure(args.assets)
+    files = [
+      "reference-manual-stm32g0x1.pdf", "datasheet-stm32g081rb.pdf",
+      "datasheet-stm32g0c1re.pdf", "pinout-nucleo.pdf", "pinout-opencplc.pdf",
+    ]
+    for f in files:
+      dst = PATH.resolve(f"{args.assets}/{f}", read=False)
+      if not FILE.exists(dst):
+        utils.download(f"{URL_FTP}/{f}", dst)
+    p.ok(f"Assets downloaded to {c.ORANGE}{args.assets}{c.END}")
+    exit_flag = True
+  if exit_flag: sys.exit(0)
+  # Flag conflict check
+  check_flags(args, ("example", flag.e), ("reload", flag.r), ("info", flag.i))
+  check_flags(args, ("example", flag.e), ("new", flag.n), ("delete", flag.d), ("get", flag.g))
+  args.name, args.new = utils.assign_name(args.name, args.new, flag.n)
+  args.name, args.example = utils.assign_name(args.name, args.example, flag.e)
+  args.name, args.reload = utils.assign_name(args.name, args.reload, flag.r)
+  args.name, args.delete = utils.assign_name(args.name, args.delete, flag.d)
+  # Setup paths
+  PATHS = forge_cfg["paths"].copy()
+  # Validate paths - no path traversal
+  for key, path in PATHS.items():
+    if ".." in path:
+      p.err(f"Invalid path in opencplc.json: {c.ORANGE}{key}{c.END} contains '..'")
+      sys.exit(1)
+    if path.startswith("/") or (len(path) > 1 and path[1] == ":"):
+      p.wrn(f"Absolute path in opencplc.json: {c.ORANGE}{key}={path}{c.END}")
+  fw_ver = args.framework or forge_cfg["version"]
+  PATHS["fw"] = PATH.resolve(f"{PATHS['framework']}/{fw_ver}", read=False)
+  PATHS["pro"] = PATHS["examples"] if args.example else PATHS["projects"]
+  # Load existing makefile info
+  make_info = None
+  if FILE.exists("makefile"):
+    lines = load_lines("makefile")
+    lines = utils.lines_clear(lines, "#")
+    make_info = utils.get_vars(lines, ["NAME", "LIB", "PRO"])
+  # Reload/info mode - get name from makefile
+  if not args.name and (args.reload or args.info):
+    if not make_info:
+      p.err(f"No {c.ORANGE}makefile{c.END} found - required for reload and info")
+      p.inf(f"Provide project name as positional argument")
+      sys.exit(1)
+    pro_rel = PATH.local(make_info["PRO"])
+    example_rel = PATH.local(PATHS["examples"])
+    if pro_rel.startswith(example_rel):
+      args.example = True
+      PATHS["pro"] = PATHS["examples"]
+    args.name = make_info["NAME"]
+  # Determine platform early for toolchain installation
+  is_embedded = True
+  if args.chip and args.chip.lower() == "host":
+    is_embedded = False
+  # Install toolchains based on platform
+  utils.install_toolchains(is_embedded, args.yes)
+  if utils.RESET_CONSOLE:
+    p.inf("Reset console after finishing work")
+    p.inf("This will reload system PATH with newly installed tools")
+    sys.exit(0)
+  # Verify compiler works
+  if not utils.verify_compiler(is_embedded):
+    compiler = "arm-none-eabi-gcc" if is_embedded else "gcc"
+    p.err(f"Compiler {c.CYAN}{compiler}{c.END} not working")
+    p.inf("Check installation and PATH")
+    sys.exit(1)
+  # Version check and clone framework
+  utils.version_check(fw_ver, forge_cfg["available-versions"],
+    f"{Ico.RUN} Check version list: {flag.F}")
+  utils.git_clone_missing(URL_CORE, PATHS["fw"], fw_ver, args.yes)
+  # Verify framework was cloned correctly
+  fw_hal = PATH.resolve(f"{PATHS['fw']}/hal", read=False)
+  fw_lib = PATH.resolve(f"{PATHS['fw']}/lib", read=False)
+  if not PATH.exists(fw_hal) or not PATH.exists(fw_lib):
+    p.err(f"Framework {c.VIOLET}{fw_ver}{c.END} is incomplete or corrupted")
+    p.inf(f"Try removing {c.ORANGE}{PATHS['fw']}{c.END} and run again")
+    sys.exit(1)
+  # Remote project download
+  if args.get:
+    url = args.get[0]
+    ref = args.get[1] if len(args.get) > 1 else None
+    args.name = utils.project_remote(url, PATHS["pro"], ref, args.name)
+  # Project list
+  PRO = utils.get_project_list(PATHS["pro"])
+  if args.example and not PRO:
+    p.wrn("Examples not downloaded")
+    utils.git_clone_missing(URL_DEMO, PATHS["examples"], "main", args.yes)
+    PRO = utils.get_project_list(PATHS["pro"])
+  # List projects
+  if args.project_list or (args.name and args.name.isdigit()):
+    if not PRO:
+      kind = "samples" if args.example else "projects"
+      p.wrn(f"No {kind} found")
+      p.inf(f"Create new with flag {flag.n}")
+      sys.exit(1)
+    i = 1
+    for name, path in PRO.items():
+      if args.project_list:
+        path = PATH.local(path)
+        path = replace_end(path, name, "")
+        nbr = f"{c.GOLD}{str(i).ljust(3)}{c.END}"
+        clr = c.TEAL if args.example else c.BLUE
+        print(f"{nbr} {c.GREY}{path}{c.END}{clr}{name}{c.END}")
+      else:
+        if int(args.name) == i:
+          args.name = name
+          break
+      i += 1
+    if args.project_list: sys.exit(0)
+  # Name validation
+  if not args.name and not args.reload and not args.info:
+    p.err(f"Name {c.YELLOW}name{c.END} not provided")
+    p.inf(f"Provide project name or use flag {flag.r}")
+    p.run(f"To reload the currently active project use flag {flag.r}")
+    sys.exit(1)
+  if args.name:
+    valid, reason = utils.validate_project_name(args.name)
+    if not valid:
+      p.err(f"Invalid project name: {c.MAGNTA}{reason}{c.END}")
+      sys.exit(1)
+  # Delete project
+  if args.delete:
+    key = next((k for k in PRO if k.lower() == args.name.lower()), None)
+    if key is None:
+      p.err(f"Project {c.MAGNTA}{args.name}{c.END} does not exist")
+      sys.exit(1)
+    try:
+      DIR.remove(PRO[key], force=True)
+      if make_info and key == make_info["NAME"]:
+        FILE.remove("makefile")
+        FILE.remove("flash.ld")
+      p.ok(f"Project {c.BLUE}{args.name}{c.END} deleted")
+      sys.exit(0)
+    except Exception as e:
+      p.err(f"Failed to delete: {e}")
+      sys.exit(1)
+  # Set project path
+  PATHS["pro"] = PATH.resolve(f"{PATHS['pro']}/{args.name}", read=False)
+  noun = "Sample" if args.example else "Project"
+  # New project
+  if args.new:
+    if args.name.lower() in (n.lower() for n in PRO.keys()):
+      p.err(f"{noun} {c.MAGNTA}{args.name}{c.END} already exists")
+      p.run(f"Use a different name or load it without flag {flag.n}")
+      sys.exit(1)
+    # Check for nested projects
+    new_name = args.name.replace("\\", "/").strip("/")
+    for existing_name in PRO.keys():
+      existing = existing_name.replace("\\", "/").strip("/")
+      if new_name.startswith(existing + "/"):
+        p.err(f"Cannot create {c.MAGNTA}{args.name}{c.END} inside existing project {c.BLUE}{existing_name}{c.END}")
+        sys.exit(1)
+      if existing.startswith(new_name + "/"):
+        p.err(f"Cannot create {c.MAGNTA}{args.name}{c.END} - project {c.BLUE}{existing_name}{c.END} already exists inside")
+        sys.exit(1)
+    # Check write permission
+    parent_dir = PATH.dirname(PATHS["pro"])
+    if not utils.check_write_permission(parent_dir):
+      p.err(f"No write permission in {c.ORANGE}{parent_dir}{c.END}")
+      sys.exit(1)
+    # Resolve chip and board
+    chip_cfg, board = resolve_chip(args.chip, args.board)
+    # If no board and no chip specified, ask about Uno
+    if not board and not args.chip:
+      if not args.yes and not utils.is_yes(f"Are you using OpenCPLC {c.TURQUS}Uno{c.END}"):
+        p.err(f"Specify board with flag {flag.b} or chip with flag {flag.c}")
+        sys.exit(1)
+      chip_cfg, board = resolve_chip("STM32G0C1", "uno")
+    # Memory override: [flash, ram] or [flash, ram, user]
+    if args.memory and len(args.memory) >= 2:
+      user_kB = args.memory[2] if len(args.memory) > 2 else 0
+      chip_cfg["flash_kB"] = args.memory[0] - user_kB
+      chip_cfg["ram_kB"] = args.memory[1]
+    # Build config
+    CFG = chip_cfg.copy()
+    CFG["pro_name"] = args.name
+    CFG["board"] = board
+    CFG["pro_ver"] = fw_ver
+    CFG["fw_ver"] = fw_ver
+    CFG["opt_level"] = args.opt_level or forge_cfg["default"]["optLevel"]
+    CFG["log_level"] = "LOG_LEVEL_INF"
+  else:
+    # Load existing project
+    if args.name.lower() not in (n.lower() for n in PRO.keys()):
+      p.err(f"{noun} {c.MAGNTA}{args.name}{c.END} does not exist")
+      if args.example:
+        p.run(f"Check available examples with flag {flag.l} or download with {flag.e}")
+      else:
+        p.run(f"Use flag {flag.n} to create a new project")
+      sys.exit(1)
+    main_h_path = PATH.resolve(f"{PRO[args.name]}/main.h", read=False)
+    if not FILE.exists(main_h_path):
+      p.err(f"File {c.ORANGE}main.h{c.END} not found in project")
+      p.inf(f"Project may be corrupted, consider recreating with {flag.n}")
+      sys.exit(1)
+    lines = load_lines(main_h_path)
+    if not lines:
+      p.err(f"File {c.ORANGE}main.h{c.END} is empty or unreadable")
+      sys.exit(1)
+    lines = utils.lines_clear(lines, "//")
+    info1 = utils.get_vars(lines, ["PRO_BOARD", "PRO_CHIP"], "_", "#define", required=False)
+    info2 = utils.get_vars(lines, ["PRO_VERSION", "PRO_FLASH_kB", "PRO_RAM_kB",
+      "PRO_OPT_LEVEL", "LOG_LEVEL", "SYS_CLOCK_FREQ"], " ", "#define", required=False)
+    info = info1 | info2
+    if not info.get("PRO_CHIP"):
+      p.err(f"File {c.ORANGE}main.h{c.END} missing PRO_CHIP definition")
+      p.inf(f"Check {c.ORANGE}{PATHS['pro']}/main.h{c.END}")
+      sys.exit(1)
+    # Get project version from main.h
+    pro_ver = info.get("PRO_VERSION", fw_ver)
+    # Resolve chip (override with args if provided)
+    stored_chip = info["PRO_CHIP"]
+    stored_board = info.get("PRO_BOARD", "").lower()
+    if stored_board == "none": stored_board = ""
+    # Board change warning
+    if args.board and args.board.lower() != "none" and stored_board:
+      pro_board = stored_board.capitalize()
+      arg_board = args.board.capitalize()
+      if arg_board.lower() != pro_board.lower():
+        p.wrn(f"Compiling for {c.TURQUS}{arg_board}{c.END}, but project was prepared for {c.TURQUS}{pro_board}{c.END}")
+    chip_cfg, board = resolve_chip(
+      args.chip or stored_chip,
+      args.board or stored_board or "none"
+    )
+    if args.board and args.board.lower() != "none":
+      board = args.board.capitalize()
+    elif not args.board and stored_board:
+      board = stored_board.capitalize()
+    else:
+      board = None
+    # Build config
+    CFG = chip_cfg.copy()
+    CFG["pro_name"] = args.name
+    CFG["board"] = board.lower() if board else None
+    CFG["pro_ver"] = pro_ver
+    CFG["fw_ver"] = fw_ver
+    CFG["flash_kB"] = int(info.get("PRO_FLASH_kB", chip_cfg["flash_kB"]))
+    CFG["ram_kB"] = int(info.get("PRO_RAM_kB", chip_cfg["ram_kB"]))
+    CFG["opt_level"] = info.get("PRO_OPT_LEVEL", "Og")
+    CFG["log_level"] = info.get("LOG_LEVEL", "LOG_LEVEL_INF")
+    CFG["freq_Hz"] = int(info.get("SYS_CLOCK_FREQ", chip_cfg.get("freq_Hz", 64000000)))
+    # Version check for project version
+    utils.version_check(pro_ver, forge_cfg["available-versions"],
+      f"{Ico.ERR} Invalid PRO_VERSION in main.h")
+    # Warn about outdated project version
+    latest = forge_cfg["available-versions"][0]
+    if pro_ver != latest and not args.example:
+      p.inf(f"Project uses {c.GREY}{pro_ver}{c.END}, latest is {c.VIOLET}{latest}{c.END}")
+    # Handle version mismatch
+    if args.example:
+      CFG["fw_ver"] = pro_ver
+      PATHS["fw"] = PATH.resolve(f"{PATHS['framework']}/{pro_ver}", read=False)
+    elif pro_ver != fw_ver:
+      fw_path = PATH.resolve(f"{PATHS['framework']}/{pro_ver}", read=False)
+      if not utils.git_clone_missing(URL_CORE, fw_path, pro_ver, args.yes, required=False):
+        p.wrn(f"Project {c.MAGNTA}{args.name}{c.END} version {c.GREY}({pro_ver}){c.END} differs from framework {c.GREY}({fw_ver}){c.END}")
+        p.wrn("This may prevent compilation or cause incorrect behavior")
+      else:
+        CFG["fw_ver"] = pro_ver
+        PATHS["fw"] = fw_path
+    # Warn about ignored flags
+    msg = f"is ignored when loading an existing {noun.lower()} — it's read from {c.ORANGE}main.h{c.END}"
+    if args.chip: p.wrn(f"Flag {flag.c} {msg}")
+    if args.memory: p.wrn(f"Flag {flag.m} {msg}")
+  # Normalize opt-level
+  opt = CFG.get("opt_level", "Og")
+  CFG["opt_level"] = opt[0].upper() + opt[1:].lower() if len(opt) > 1 else opt
+  valid_opts = ("O0", "Og", "O1", "O2", "O3")
+  if CFG["opt_level"] not in valid_opts:
+    p.wrn(f"Unknown optimization level {c.MAGNTA}{opt}{c.END}, using {c.CYAN}Og{c.END}")
+    p.inf(f"Valid options: {', '.join(valid_opts)}")
+    CFG["opt_level"] = "Og"
+  if CFG["platform"] == "STM32" and CFG["opt_level"] in ("O2", "O3"):
+    p.wrn(f"Optimization {c.MAGNTA}{CFG['opt_level']}{c.END} may cause issues on STM32 (timing, debugging)")
+    if not args.yes and not utils.is_yes(f"Continue with {c.CYAN}{CFG['opt_level']}{c.END}"):
+      p.inf(f"Using {c.CYAN}Og{c.END} instead")
+      CFG["opt_level"] = "Og"
+  # Info mode
+  if args.info:
+    rel_path = PATH.local(PATHS["pro"])
+    path_prefix = replace_end(rel_path, CFG["pro_name"], "")
+    msg = f"{c.GREY}{path_prefix}{c.END}{c.BLUE}{CFG['pro_name']}{c.END}"
+    sample_msg = f" {c.RED}(sample){c.END}" if args.example else ""
+    p.inf(f"Project: {msg}{sample_msg}")
+    p.gap(f"Platform: {c.CYAN}{CFG['platform']}{c.END}")
+    p.gap(f"Board {flag.b}: {c.TURQUS}{str(CFG.get('board') or 'None').capitalize()}{c.END}")
+    p.gap(f"Chip {flag.c}: {c.PINK}{CFG['chip']}{c.END}")
+    p.gap(f"Project version: {c.MAGNTA}{CFG['pro_ver']}{c.END}")
+    p.gap(f"Framework version: {c.MAGNTA}{CFG['fw_ver']}{c.END}")
+    if CFG["platform"] == "STM32":
+      p.gap(f"FLASH{c.GREY}/{c.END}RAM {flag.m}: {c.CYAN}{CFG['flash_kB']}{c.END}kB{c.GREY}/{c.END}{c.CYAN}{CFG['ram_kB']}{c.END}kB")
+      p.gap(f"System frequency clock: {c.CYAN}{CFG.get('freq_Hz', 64000000)}{c.END}Hz")
+    p.gap(f"Optimization level {flag.o}: {c.PINK}{CFG['opt_level']}{c.END}")
+    p.gap(f"Log level: {c.BLUE}{CFG['log_level'].replace('LOG_LEVEL_', '')}{c.END}")
+    p.gap(f"Last modification: {utils.last_modification(PATHS['pro'], ext=['.c','.h'])}")
+    sys.exit(0)
+  # Generate project
+  generate_project(CFG, PATHS, forge_cfg, is_example=args.example)
+
+if __name__ == "__main__":
+  main()