Python object model

8 min readScripts

The ready-made scada object in Python scripts and its members for tags, screens, objects, recipes, the system and the outside world (database, file, program).

Predefined names

The only names that are visible without an import are: scada, HMIRuntime, SmartTags, ScreenItems, Layers, DataSet and open(). In event code and actions, Item and Parent are also available. os, shutil, glob, tempfile, subprocess, pyodbc and pathlib are not built in; they are brought in with import.

Member names are looked up first as written, then by matching snake_case ↔ PascalCase: back_color and BackColor are the same property. Case matters. The rules for tags, object properties, screens, DataSet, report records, system tags, sessions and notifications are the same as in VBS; the difference is that the value conversion is that of Python.

Tag operations

Member	Description
`scada.read("Ad", varsayılan)`	Reads the value. If the tag does not exist, raises `KeyError`; if a default is given, returns it.
`scada.write("Ad", değer)`	Converts the value to the type of the tag and writes it. A number exceeding the limit raises `ValueError`; an incompatible type raises `TypeError`.
`scada.read_many(["A", "B"])`	Reads in sequence and returns a list.
`scada.write_many({"A": 1, "B": 2})`	Writes a dictionary or a list of (name, value) pairs; the first error raises an exception, and the values before it remain written.
`scada.tags["Ad"]`	Reads / writes like a dictionary; `in`, `len` and `for` work.
`scada.tag_exists("Ad")`, `scada.tag_names()`	Whether a tag exists, the tag names in the project.
`scada.get_bit("Ad", bit)`, `scada.set_bit("Ad", bit, True)`	Reads / changes one bit of an integer tag (0 – 31); does not touch the other bits.
`scada.wait_for("Ad", değer, zaman_asimi=10.0, aralik=0.1)`	Waits until the tag reaches the value (if no value is given, until it is "true"); returns `None` if the time runs out. `scada.wait_for(işlev, …)` calls the parameterless function until it returns true.
`scada.tagset(["A", "B"])`	TagSet: `add`, `remove`, `read()` (dictionary), `write(eşleşme)`, `items()`, `count`.
`scada.report_add("Rapor")`	Adds a record to the report and returns the record number. `ValueError` if the report does not exist.

Tag object (`scada.tag("Ad")`)

.value (reads / writes), .read(), .write(değer), .quality (192 good, 84 out of range, 8 no connection, 4 undefined, 0 bad), .timestamp, .last_error, .error_text, .datetime, .name, .prefix, .type.

VBS habit

HMIRuntime.Tags("Ad") (.Value = x writes directly; if an error occurs, no exception is thrown and .LastError is filled), HMIRuntime.Tags("Ad").Read() / .Write(değer), HMIRuntime.Tags.CreateTagSet(), SmartTags["Ad"] (reads / writes the value itself), HMIRuntime.BaseScreenName, HMIRuntime.ActiveScreen, HMIRuntime.Language, HMIRuntime.Trace.

Screen and object

Member	Description
`scada.open_screen("Sayfa", onek="")`	Changes the main screen. Raises `ValueError` if the screen does not exist.
`scada.open_window("Sayfa", onek="")`, `scada.close_window(ad)`	Opens / closes it in a pop-up window.
`scada.back()`, `scada.forward()`, `scada.open_home()`	Previous, next, start screen.
`scada.screen`	The screen in front.
`scada.screens["Sayfa"]`	A mapping of open screens only; a closed screen gives `KeyError`.
Screen: `.items["Nesne"]`	An object on the screen (`items[0]`, `in`, `len` and `for` also work).
Screen: `.name`, `.access_path`, `.width`, `.height`, `.back_color`, `.zoom`, `.layers`, `.dataset`, `.refresh()`, `.activate()`, `.parent`	The screen's name, path, dimensions, its 32 layers and its own value store.
Object: `.visible`, `.enabled`, `.left`, `.top`, `.width`, `.height`, `.text`, `.back_color`, `.fore_color`, `.border_color`, `.font_name`, `.font_size`, `.font_bold`, `.font_italic`, `.font_underline`, `.process_value`, `.output_value`, `.rotation_angle`, `.transparency`, `.flashing_enabled`, `.min`, `.max`, `.unit`, `.layer`, `.tooltip`, `.parent`, `.name`, `.type`, `.activate()`	The written value is valid for the duration of the session; it is not written to the project. `.get("Özellik")` / `.set("Özellik", değer)` read / write the property whose name is given as text; the object's own property names can also be used directly like attributes. A nonexistent name raises `AttributeError`.
Layer: `sayfa.layers[n]`	`.visible`, `.name`, `.min_zoom`, `.max_zoom` (n: 0 – 31, the same as the `.layer` value of the object).
`scada.dataset["ad"]`	Name / value pairs held in memory (reset when the project is loaded); `get`, `pop`, `keys`, `items`, `clear`, `setdefault` and `in` are also available. `sayfa.dataset` is per screen.
`scada.rgb(r, g, b)`, `scada.color(sayı)`	Produces a color number / converts it to a `"#rrggbb"` string.

Predefined names in event code and actions: Item (the object of the event; for a screen event, the screen), ScreenItems (the objects on the event's screen), Parent (the screen of the event), Layers, DataSet. These do not exist in modules.

Recipe

scada.recipes is the list of the recipe names in the project. scada.recipe("Ad") returns a recipe object (a recipe that does not exist raises KeyError); the recipe records are in the record store of the recipe.

Member	Description
`.records()`, `.names()`, `.count`, `.fields`, `.name`	Records (dictionary with field names), record names, record count, field names.
`.get("Kayıt", varsayılan)`, `reçete["Kayıt"]`	Single record; if absent, the default / `KeyError`.
`.insert(değerler, ad="")`	Adds a new record; fields that are not given take their default value; the limits are checked. Returns the record name.
`.update("Kayıt", değerler)`, `.delete("Kayıt")`	Changes the given fields (the others are kept) / deletes the record.
`.read_tags()`	The current values of the field tags (`{alan: değer}`).
`.write_tags(kaynak)`	The source (record name or dictionary) is written to the tags of the fields; there is no handshake. Returns the number of fields written.

Recipe operations are written to the event log with type recete ("… added (Python script)"). Details: Recipe design.

System

Member	Description
`scada.user`, `scada.user_name`	Name and full name of the logged-in user; an empty string if there is no session.
`scada.login_dialog()`, `scada.login(kullanıcı, şifre)`, `scada.logout()`	Login window (`True` if login succeeded), login without opening a window, logout.
`scada.has_permission("yetki")`	Whether the user has that authorization (authorization code, name or level). If there is no such authorization in the project: `ValueError`; if there is no session: `False`.
`scada.language`	Live language number; if assigned, the language changes (a code such as `"en"` can also be given).
`scada.project.name`, `scada.project.path`, `scada.computer`, `scada.windows_user`	Project, computer and Windows user.
`scada.now()`	Current local date and time (`datetime`).
`scada.msgbox(metin, düğmeler=0, başlık="")`	Message box; returns the number of the button pressed (1 OK, 2 Cancel, 3 Stop, 4 Retry, 5 Ignore, 6 Yes, 7 No). Constants: `scada.OK`, `YES`, `NO` …; button sets `scada.YES_NO` …; icons `scada.ICON_QUESTION` …
`scada.inputbox(metin, başlık="", varsayılan="")`	Input box; the typed text, or `None` for Cancel / Esc. The built-in `input()` opens the same box.
`scada.notify(metin)`	Shows an info window and continues without waiting.
`print(…)`, `scada.trace(…)`	Joins the values in one line and writes it to the script diagnostics and the event log.
`scada.sleep(saniye)`, `scada.stop()`	Waits (does not lock the interface; does not count towards the 30 s limit) / closes Live.

External world (depends on permission)

Permission	Members
Database connection	`scada.db.connect("DSN=Ad;UID=k;PWD=s;")` or `pyodbc.connect(…)` (`import pyodbc`). Connection: `query(sql, parametreler)` (list of dictionaries), `scalar(sql, parametreler)`, `execute(sql, parametreler)` (cursor; `.rowcount`), `close()`, `with`. Cursor: `fetchone`, `fetchall`, `fetchmany`, `description`. Parameter marker: `?`.
Program execution	`scada.run(komut, goster=1)`, `os.system`, `os.startfile`, `subprocess.run` / `call` / `Popen`. The program is started but not waited for; the exit code is not real (it appears as 0).
File access	`open(yol, kip, encoding=…)` (`r`, `w`, `a`, `x`, `b`), `os` (`listdir`, `mkdir`, `makedirs`, `remove`, `rename`, `rmdir`, `stat`, `walk`, `path.*`), `shutil` (`copy`, `move`, `copytree`, `rmtree`), `glob.glob`, `pathlib.Path`, `tempfile.gettempdir` / `mkdtemp`.

The database connection is stateless: each command opens and closes its own connection (no transaction, no temporary #tablo, no SET). The connection is tried immediately; a wrong DSN causes an error at connect. At most 5000 rows are returned and a command runs for at most 15 seconds. commit() and rollback() have no effect.
Relative file paths are resolved against the project folder (against a temporary folder if there is no project). Writing to the program folder and to the open project file is not possible (PermissionError). In text mode, if encoding is not given, reading tries the order BOM / UTF-8 / Windows-1254, and writing uses UTF-8 without BOM.
While the permission is off, the relevant call raises PermissionError (it can be caught with try / except).

Limitations and points to note

Unsupported members (HMIRuntime.Logging, AlarmLogs, DataLogs, Alarms, MenuToolBarConfig) raise NotImplementedError when called and write a diagnostics line.
Writing an object property in a 3D screen raises NotImplementedError.
Calls are awaited automatically; await is not written.