Product: Mingcedar CONTROL

Python Projects and Packages | Mingcedar

Confirm the Script service is available. Code management requires super-admin and integration:manage; Run Test also requires integration:execute. Python Packages requires system:view and system:manage. Follow the exercises for calculations, dependencies, events, and Tag access.

Published 2026-10-25T12:48:42.636893435Z Updated 2026-10-25T12:48:42.636892654Z

<div class="manual-doc-article manual-doc-article-section"><h2 id="python-scripting">Developer tutorial: Python Projects and Packages</h2>

Use CPython 3.13 to create projects, reuse functions, install dependencies, read Tags, configure events, and authorize writes.

<h3 id="python-scripting-item-1">Before you start</h3>

Confirm the Script service is available. Code management requires super-admin and integration:manage; Run Test also requires integration:execute. Python Packages requires system:view and system:manage. Follow the exercises for calculations, dependencies, events, and Tag access.

<ul>

<li>Code creates projects and edits files. The toolbar's Run Test executes the selected Python file; unsaved changes change the button to Save & Test.</li>

<li>Run configures when an event fires and which actions it executes. Records shows event execution results.</li>

<li>Settings → Python → Python Packages selects a project and manages its packages. Advanced Project Settings manages entrypoints, runtime limits, the server offline directory, environment variables, and Secrets.</li>

<li>Replace angle-bracket placeholders. Keep the tutorial filenames, function names, and practice values as shown.</li>

</ul>

</article>

<h3 id="python-scripting-item-2">1. Create the project and two Python files</h3>

Location: Configuration Center → script → Code. Create the project, then add its files.

<ol>

<li>Click Manage Projects, then New in the dialog.</li>

<li>Enter Equipment Integration as the Project name and click Create Project. Close the dialog and select this project in the Code page dropdown.</li>

<li>Click the new-file + beside common/, enter scaling, and click Create. The editor adds .py.</li>

<li>Create main under scripts/ in the same way. If main.py already exists, select it instead.</li>

<li>Check the editor title: the two paths must be common/scaling.py and scripts/main.py.</li>

</ol>

<div class="manual-code" data-code-language="text"><div class="manual-code-toolbar">TextText<button type="button" data-copy-code data-copied="Copied" data-failed="Select and copy the code" aria-label="Copy code: Text">Copy code</button></div><pre tabindex="0" class="docs-code-block shiki github-light" style="background-color:#fff;color:#24292e" tabindex="0"><code>Project/

├── scripts/

│ ├── __init__.py

│ └── main.py

└── common/

├── __init__.py

└── scaling.py</code></pre></div>

Expected result Both files are selectable with the expected paths. The tree shows the file layout.

<div class="doc-step-troubleshooting">If the result differs<ul>

<li>If creation controls are unavailable, check script management permission. Correct a misplaced file before copying code.</li>

</ul></div>

</article>

<h3 id="python-scripting-item-3">2. Save the shared function</h3>

Convert the input range 0–100 to 0–10.

<ol>

<li>Select common/scaling.py and verify the editor path.</li>

<li>Replace its contents with the complete code below and click Save.</li>

<li>Wait for the Unsaved marker to disappear before changing files. This module defines a function and does not need to run separately.</li>

</ol>

<div class="manual-code" data-code-language="python"><div class="manual-code-toolbar">common/scaling.pyPython<button type="button" data-copy-code data-copied="Copied" data-failed="Select and copy the code" aria-label="Copy code: common/scaling.py">Copy code</button></div><pre tabindex="0" class="docs-code-block shiki github-light" style="background-color:#fff;color:#24292e" tabindex="0"><code># common/scaling.py

def scale_linear(value, input_min, input_max, output_min, output_max):

if input_max == input_min:

raise ValueError("Input range must not be zero")

return output_min + (value - input_min) * (output_max - output_min) / (input_max - input_min)

</code></pre></div>

Expected result No output is expected until main.py calls the saved function.

</article>

<h3 id="python-scripting-item-4">3. Call the function and inspect the console</h3>

Events call main(ctx); the Code page calls the same function through the __main__ block.

<ol>

<li>Select scripts/main.py, paste the complete code below, and save.</li>

<li>Keep main.py selected and click Run Test in the toolbar. Do not run scaling.py.</li>

<li>Inspect the execution status and output in Console below the editor.</li>

<li>Change 50 to 25 in main({"raw": 50}), save, and run again. Verify 2.5, then restore 50.</li>

</ol>

<div class="manual-code" data-code-language="python"><div class="manual-code-toolbar">scripts/main.pyPython<button type="button" data-copy-code data-copied="Copied" data-failed="Select and copy the code" aria-label="Copy code: scripts/main.py">Copy code</button></div><pre tabindex="0" class="docs-code-block shiki github-light" style="background-color:#fff;color:#24292e" tabindex="0"><code># scripts/main.py

from ..common.scaling import scale_linear

def main(ctx):

value = scale_linear(float(ctx.get("raw", 50)), 0, 100, 0, 10)

print("Scaled value:", value)

return {"scaled": value}

if __name__ == "__main__":

main({"raw": 50})

</code></pre></div>

Expected result Expect Scaled value: 5.0 with status Completed, then 2.5 after changing the input.

<div class="doc-step-troubleshooting">If the result differs<ul>

<li>Completed with no output: verify the selected file and its if __name__ == "__main__" block.</li>

<li>ImportError: keep both files in the same project under scripts/ and common/. Do not run this relative-import example directly from an OS terminal.</li>

</ul></div>

</article>

<h3 id="python-scripting-item-5">Import rules for shared functions and custom packages</h3>

scripts/main.py uses from ..common.scaling import scale_linear. A file at scripts/controls/main.py needs three leading dots. Absolute imports must use the actual package value in the project manifest.

<ul>

<li>Within a project, common/ is built and applied with the calling scripts. Use a relative import; no installation in Python Packages is needed. Save changes and verify the applied runtime version.</li>

<li>Across projects, build custom code as a Wheel with an explicit version and dependency declarations. Install it in each consuming project using the workflow below. Then use a normal import with the package's actual module name, not its Wheel filename.</li>

<li>Do not extend sys.path to host folders or import another project through its storage path.</li>

</ul>

Expected result Save changes to scaling.py and rerun main.py. Cross-project reuse requires an installed dependency, not another project’s path.

</article>

<h3 id="python-scripting-item-6">4. Identify this project’s Python runtime</h3>

Dependencies are installed per project, not inherited from the preparation machine or system Python. The Packages page requires the system permissions listed above.

<ul>

<li>json, csv, sqlite3, datetime, urllib, and smtplib are standard-library modules and need no installation.</li>

<li>Bundled packages include requests, psycopg, PyMySQL, pyodbc, paho-mqtt, websocket-client, and cryptography. New projects install them when their environment is first built. Existing projects can use Add Bundled Packages; previously selected versions are retained.</li>

<li>Install additional packages such as openpyxl for Excel as needed. A pyodbc database connection also requires the corresponding ODBC driver on the server.</li>

<li>Distribution names can differ from imports: PyMySQL → pymysql; websocket-client → websocket.</li>

</ul>

<ol>

<li>Open Settings → Python → Python Packages and select Equipment Integration.</li>

<li>Read Runtime above the package list and record the Python version, operating system, and architecture. The current target is Python 3.13.</li>

<li>Check the package list for the names and versions needed in this exercise. Its heading may read Project Packages, Prepared Packages, or Installed Packages depending on the project's state.</li>

<li>For a Linux container, use the target inside the container. Native Windows and Linux deployments use their respective targets.</li>

</ol>

Expected result Use the confirmed project runtime target to select bundled packages or compatible Wheels.

</article>

<h3 id="python-scripting-item-7">5. Choose bundled packages or prepare Wheels and dependencies</h3>

Bundled packages need no download. Download other dependencies at approved exact versions on a preparation machine matching the target OS, CPU and Python 3.13. Run these commands only there.

<ol>

<li>Check the project package list first. If psycopg and PyMySQL are available as bundled packages, click Add Bundled Packages, check every package proposed in the preview, and continue at step 7 without downloading them again.</li>

<li>For another third-party package or a specific version, run python --version on an online preparation machine matching the server's OS, architecture, and Python version. This example prepares psycopg and PyMySQL for the SQL tutorial; omit one package and its import check if using only one database.</li>

<li>Replace each <approved-version> with the exact version of its package. Keep the quotes; do not execute placeholders literally.</li>

<li>Run pip download, wait for success, and inspect ./wheelhouse for both the main packages and their dependency Wheels.</li>

<li>Build custom packages as .whl files with explicit versions and dependency declarations. Optionally run the offline installation and import check below in a temporary virtual environment to verify complete dependencies and actual import names before upload.</li>

</ol>

<div class="manual-code" data-code-language="bash"><div class="manual-code-toolbar">ShellShell<button type="button" data-copy-code data-copied="Copied" data-failed="Select and copy the code" aria-label="Copy code: Shell">Copy code</button></div><pre tabindex="0" class="docs-code-block shiki github-light" style="background-color:#fff;color:#24292e" tabindex="0"><code># Run on a preparation machine matching the target OS and CPU, with Python 3.13.

# Replace the version placeholders with your approved exact versions.

python -m pip download --only-binary=:all: --dest ./wheelhouse "psycopg[binary]==<approved-version>" "PyMySQL==<approved-version>"

# Optional local verification in a disposable preparation environment:

python -m venv ./dependency-check

# Use dependency-check/bin/python (Linux) or dependency-check\Scripts\python.exe (Windows):

<venv-python> -m pip install --no-index --find-links=./wheelhouse "psycopg[binary]==<approved-version>" "PyMySQL==<approved-version>"

<venv-python> -c "import psycopg, pymysql; print('Dependencies ready')"</code></pre></div>

Expected result Confirm bundled packages in the preview or the required .whl files in the download folder. The offline probe prints Dependencies ready; verify again in the target project.

</article>

<h3 id="python-scripting-item-8">6. Upload Wheels and review the installation preview</h3>

Prefer a matching preparation environment. If cross-downloading is necessary, specify --platform, --python-version 3.13, --implementation cp, --abi cp313, and --only-binary=:all:. The platform tag must match the actual runtime, including glibc/musl compatibility.

<ol>

<li>Check each Wheel's distribution, version, Python/ABI/platform tags, and SHA-256. Keep one intended version per distribution and include all transitive dependencies.</li>

<li>In Settings → Python → Python Packages, select the project and click Add to select the required .whl files. You can also upload a ZIP containing only the complete Wheel dependency set, or drop files onto the package list.</li>

<li>Review the Review Installation preview for added or updated packages and versions. If it reports missing dependencies, add the missing Wheels before submitting the installation.</li>

<li>Use the server directory only when needed: expand Advanced Project Settings → Server Offline Directory, copy regular .whl files to the displayed Project directory, and click Refresh Inventory. Then return to the package list, expand Offline Directory Import, and click Check Directory Packages. Do not place ZIPs, source archives, folders, or symlinks in that directory.</li>

<li>For Linux containers, use the path inside the container and ensure the service account can read it. Refresh Inventory only scans the directory; complete the preview and installation in the next step.</li>

</ol>

Expected result The preview shows the intended changes without compatibility, version, or missing-dependency errors. The runtime is unchanged.

</article>

<h3 id="python-scripting-item-9">7. Install packages and verify imports</h3>

Submit after reviewing the preview. New projects can install packages for Code-page runs; projects with a running version apply the new version after checks pass.

<ol>

<li>After reviewing the preview, if the required packages are already in this project's package list, proceed to the Code-page import check. Otherwise click Install in Project or Install and Apply as shown. The former prepares a project without a running version for manual runs; the latter checks and applies a new runtime version.</li>

<li>If you submitted an installation, wait for the “Packages are installed in the project” or “Packages installed and applied” result. The first result permits manual runs from Code, but an entrypoint must be configured below before an event can run automatically.</li>

<li>Return to Code and create check_dependencies under scripts/. Paste the code below. For PostgreSQL only, remove import pymysql and the PyMySQL version(...) print line; for MySQL only, remove import psycopg and the psycopg version(...) print line. Then save.</li>

<li>Select check_dependencies.py, click Run Test, and compare Python and installed-package versions in Console.</li>

</ol>

<div class="manual-code" data-code-language="python"><div class="manual-code-toolbar">scripts/check_dependencies.pyPython<button type="button" data-copy-code data-copied="Copied" data-failed="Select and copy the code" aria-label="Copy code: scripts/check_dependencies.py">Copy code</button></div><pre tabindex="0" class="docs-code-block shiki github-light" style="background-color:#fff;color:#24292e" tabindex="0"><code># scripts/check_dependencies.py

import sys

from importlib.metadata import version

import psycopg

import pymysql

print("Python:", sys.version.split()[0])

print("psycopg:", version("psycopg"))

print("PyMySQL:", version("PyMySQL"))

print("Dependencies ready")

</code></pre></div>

Expected result Console reports Python 3.13, the versions of the one or two packages installed, and Dependencies ready.

<div class="doc-step-troubleshooting">If the result differs<ul>

<li>ModuleNotFoundError: match the distribution to its actual import name, then check this project's package list and installation result. Supply missing Wheels, review the preview again, and install.</li>

<li>wheel_incompatible: prepare Wheels for the actual runtime target. wheel_version_conflict: retain one version per distribution in the upload set.</li>

</ul></div>

</article>

<h3 id="python-package-maintenance">Update or remove project packages</h3>

The package list applies to the selected project. Updates and removals show a preview before installation or application.

<ul>

<li>To update, choose Add and upload the new package version with its dependencies. Review the version changes before installing. Keep one version per distribution.</li>

<li>To remove, choose Delete beside a package, review the list, then Confirm Delete. Resolve dependency warnings if other packages still require it.</li>

<li>Uploads accept .whl files and Wheel bundle ZIPs, not source archives, installers, or requirements.txt. Select at most 256 files with a combined size below 512 MiB.</li>

<li>Installation uses bundled or supplied Wheels; missing dependencies are not downloaded automatically. Running pip install on a preparation computer does not change the host project environment.</li>

</ul>

</article>

<h3 id="python-scripting-item-10">8. Configure the runtime entrypoint</h3>

Location: Settings → Python → Python Packages → Advanced Project Settings → Project Runtime Configuration. Register the verified main(ctx) as an event entrypoint.

<ol>

<li>Select the project and inspect hqapp.toml. Keep the generated id, package, python, and worker settings.</li>

<li>Locate the [[entrypoints]] item with id = "main". Edit an existing item rather than adding a duplicate id.</li>

<li>Set target to the actual package value followed by .scripts.main:main. For package equipment_integration, that is equipment_integration.scripts.main:main; do not copy a package name absent from your manifest.</li>

<li>For this exercise use class = "normal-python", timeout_seconds = 30, and max_concurrency = 1. Click Save and Apply Configuration.</li>

<li>Wait for successful application before binding the action on Run. Source persistence alone does not establish that the runtime version is active.</li>

</ol>

Expected result After application, the entrypoint appears in the action’s Script selector. If absent, check the save result and target.

</article>

<h3 id="python-schedule">9. Create a scheduled event and bind a script action</h3>

The event triggers every 60 seconds; its action selects the calculation script. Keep it disabled until binding is complete.

<ol>

<li>Open Configuration Center → script → Run → Events and click New Event.</li>

<li>Enter ScaleCheck as Event Name / Code. Choose Timed Loop, set Interval (seconds) to 60 and Minimum Trigger Interval to 0. Uncheck Event Enabled and click Save Event.</li>

<li>Select ScaleCheck, then New Action under Actions Bound to Event. Enter ScaleValue as Action Code and choose Script Action.</li>

<li>Select the registered main script in Script, keep the action enabled, and click Save Action Binding.</li>

<li>Edit Event Properties, enable the event, and save. After a full interval, inspect the matching event, action, timestamp, and result in Records.</li>

<li>After the exercise, disable the event in Event Properties and save to stop the schedule.</li>

</ol>

Expected result Records shows successful execution. The details show {scaled: 5.0} as the return value and Scaled value: 5.0 in the output. main(ctx) defaults raw to 50, so no extra input is needed.

<div class="doc-step-troubleshooting">If the result differs<ul>

<li>No record: check that both event and action are enabled, a script is selected, and the Script service is available.</li>

<li>Failed record: inspect that execution’s error. Correct an invalid target in Project Configuration and apply it again.</li>

<li>Wrong result: match the event, action, and timestamp; a previous Code-page run does not verify the schedule.</li>

</ul></div>

</article>

<h3 id="python-scripting-item-11">10. Read a Tag and verify quality</h3>

Replace the URI directly inside tags.read(...) with a local TagRef. Run Test grants read scope from literal arguments, not variables. Compare value and quality with Tag Test. tags.read_many([...]) accepts up to 256 unique inputs; check each item’s ok.

<ol>

<li>Choose a Tag showing a valid number in Tag Test and record its value and quality.</li>

<li>Obtain the complete hq://io/... TagRef for the current local Site. A device-code.tag-code string and this URI are different representations. Remote Tags are outside Run Test's local read scope.</li>

<li>Create read_value under scripts/ and replace the example URI inside tags.read(...) with the actual URI.</li>

<li>Save and run read_value.py with Run Test; inspect Value and Quality.</li>

<li>For a changing signal, compare near the same acquisition time. Establish good quality before evaluating value differences.</li>

</ol>

<div class="manual-code" data-code-language="python"><div class="manual-code-toolbar">scripts/read_value.pyPython<button type="button" data-copy-code data-copied="Copied" data-failed="Select and copy the code" aria-label="Copy code: scripts/read_value.py">Copy code</button></div><pre tabindex="0" class="docs-code-block shiki github-light" style="background-color:#fff;color:#24292e" tabindex="0"><code># scripts/read_value.py

from hqcontrol import tags

def main(ctx):

response = tags.read("hq://io/<io-domain-id>/<device-uid>/<tag-uid>")

if not response or response.get("ok") is not True:

snapshot = response["value"]

if not tags.is_good_quality(snapshot):

print("Value:", snapshot.get("value"), "Quality:", snapshot.get("quality"))

return {"value": snapshot.get("value")}

main({})

</code></pre></div>

Expected result Expect the target value with good quality; missing or poor-quality data remains an error.

</article>

<h3 id="python-scripting-item-12">Direct typed methods</h3>

The workbench also provides ReadTagBoolean, ReadTagInteger, ReadTagDouble, ReadTagString, ReadTagJson, ReadTagDateTime, ReadTagQuality, and matching WriteTag methods without an import. For Run Test, put a literal local Tag name in the first argument of each read; a variable does not grant read scope. ReadTagQuality maps status to good/bad; use tags.read for detailed quality and timestamps.

<div class="manual-code" data-code-language="python"><div class="manual-code-toolbar">PythonPython<button type="button" data-copy-code data-copied="Copied" data-failed="Select and copy the code" aria-label="Copy code: Python">Copy code</button></div><pre tabindex="0" class="docs-code-block shiki github-light" style="background-color:#fff;color:#24292e" tabindex="0"><code>if ReadTagQuality("<device-code>.<tag-code>") != "good":

print(ReadTagDouble("<device-code>.<tag-code>", 0.0))

calculated = ReadCalculatedTag("<calculated-tag-code>", None)

if calculated is None:

print(calculated)</code></pre></div>

</article>

<h3 id="python-scripting-item-13">11. Save a controlled write function</h3>

Save as common/tag_control.py. The function takes TagRef and expected from the read response, writes once, and checks status. Replace 0–100 with the equipment range. Run Test grants no write scope; call from a formal action with target read/write scope.

<ol>

<li>Create tag_control under common/, paste the code below, and save. Defining this function does not submit a write.</li>

<li>Before using it in a formal action, choose an approved local numeric setpoint, confirm that 12.5 is within its allowed range, and record the original value.</li>

<li>Verify that the action trigger grants read and write scope for the same target TagRef, the target is writable, and current acquisition quality is good.</li>

</ol>

<div class="manual-code" data-code-language="python"><div class="manual-code-toolbar">common/tag_control.pyPython<button type="button" data-copy-code data-copied="Copied" data-failed="Select and copy the code" aria-label="Copy code: common/tag_control.py">Copy code</button></div><pre tabindex="0" class="docs-code-block shiki github-light" style="background-color:#fff;color:#24292e" tabindex="0"><code># common/tag_control.py

from hqcontrol import tags

def write_setpoint(read_response, value):

if isinstance(value, bool) or not isinstance(value, (int, float)) or not 0 <= value <= 100:

raise ValueError("Setpoint must be a number between 0 and 100")

if not read_response or read_response.get("ok") is not True:

tag_ref = read_response.get("tagRef")

if not isinstance(tag_ref, str) or not tag_ref.startswith("hq://io/"):

snapshot = read_response["value"]

if not tags.is_good_quality(snapshot):

result = tags.write(tag_ref, float(value), value_type="number",

reason="Approved setpoint update", expected=snapshot)

if (result.get("accepted") is not True or result.get("status") != "done"

or result.get("outcomeUncertain") is True

or result.get("operatorVerificationRequired") is True

or result.get("transportOnly") is True):

raise RuntimeError("Verify command " + str(result.get("commandId")) +

"; status=" + str(result.get("status")) +

"; accepted=" + str(result.get("accepted")))

return result

</code></pre></div>

Expected result Saved; writing occurs only when write_setpoint is called.

</article>

<h3 id="python-write-entry">12. Controlled write pattern for a formal action</h3>

Use this entrypoint in a formal action; Run Test grants no write scope. The trigger context must include the target TagRef and satisfy permission, equipment, and runtime conditions.

<ol>

<li>Create write_setpoint under scripts/, copy the entrypoint below, and complete the replacements before saving. Saving source alone does not submit a write.</li>

<li>Replace the URI inside tags.read(...) with the approved local setpoint TagRef, and replace 12.5 with the approved value.</li>

<li>Before configuring the formal action in Run, confirm that its trigger grants read/write scope for this same TagRef and that the write cannot retrigger the action in a loop. Do not use Code-page Run Test to verify writing.</li>

<li>After the formal action runs, inspect command results in Records and subsequent acquisition in Tag Test. If uncertain, reconcile the commandId before submitting another write.</li>

</ol>

<div class="manual-code" data-code-language="python"><div class="manual-code-toolbar">scripts/write_setpoint.pyPython<button type="button" data-copy-code data-copied="Copied" data-failed="Select and copy the code" aria-label="Copy code: scripts/write_setpoint.py">Copy code</button></div><pre tabindex="0" class="docs-code-block shiki github-light" style="background-color:#fff;color:#24292e" tabindex="0"><code># scripts/write_setpoint.py

from hqcontrol import tags

from ..common.tag_control import write_setpoint

def main(ctx):

return write_setpoint(response, 12.5)

</code></pre></div>

Expected result The function returns only for accepted=true, status=done, and no uncertainty or operator-verification flags. Verify later normal collection. For proxied or other states, retain commandId for reconciliation without repeating the write.

</article>

<h3 id="python-runtime-status">Inspect Script runtime status</h3>

Location: Configuration Center → script → Status. Overview and Workers show service health and execution resources; use Records for individual executions.

<ul>

<li>Overview shows service health, worker summaries, triggers, connectors, scheduler lanes, and collected Tag quality.</li>

<li>Workers shows ready, busy, starting, and draining states, along with cold starts, warm hits, and concurrency-rejection counts.</li>

<li>A healthy service does not mean every business action succeeded. For queued or failed work, inspect the event, action, timestamp, and error in Records.</li>

</ul>

</article>

<h3 id="python-scripting-item-14">Expected results and troubleshooting</h3>

After the examples, the console should show 5.0, dependency versions should match the package list, and read quality should be good. Confirm writes through command status and later collected values.

<ul>

<li>ModuleNotFoundError: check distribution and actual import names, transitive dependencies, the current project's package list, and the installation result.</li>

<li>wheel_incompatible: obtain matching cp313, OS, and CPU Wheels. For containers, match the environment inside the container.</li>

<li>wheel_version_conflict: retain one version per distribution in the upload set, then review a new installation preview.</li>

<li>Relative import error: check script depth and leading dots, or use the actual manifest package name.</li>

<li>Missing Tag data: verify scope, TagRef, collection quality, and service state. A fallback is a display value, not proof that field data is healthy.</li>

<li>Write timeout, pending_verification, or outcome_uncertain: reconcile the commandId and field readback; do not resend automatically.</li>

</ul>

</article>

</div>

Figure 1: Import shared functions within a project

Import common/ functions relatively from scripts/ without installing a package. Build a Wheel to reuse code across projects.

</figcaption>

</figure>

Figure 2: Manage Python packages per project

Select the project and check its runtime before adding bundled packages or uploading Wheels.

</figcaption>

</figure>

Figure 3: Upload and installation paths

Web upload is the usual path. The server offline directory is under advanced settings and still requires an installation review.

</figcaption>

</figure>

</div>