gxw3call 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Potentially problematic release.


This version of gxw3call might be problematic. Click here for more details.

@@ -0,0 +1,6 @@
1
+ __pycache__/
2
+ *.gx3
3
+ *.log
4
+ .venv/
5
+ .vscode/
6
+ dist/
gxw3call-0.1.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Kim Jinyeol
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,157 @@
1
+ Metadata-Version: 2.5
2
+ Name: gxw3call
3
+ Version: 0.1.0
4
+ Summary: Drive GX Works3 from Python through its Open Interface (GXW3Call.dll)
5
+ Project-URL: Homepage, https://github.com/Wadangzz/py-gxw3call
6
+ Project-URL: Issues, https://github.com/Wadangzz/py-gxw3call/issues
7
+ Author: Kim Jinyeol
8
+ License-Expression: MIT
9
+ License-File: LICENSE
10
+ Keywords: automation,com,gx works3,melsec,mitsubishi,plc
11
+ Classifier: Development Status :: 3 - Alpha
12
+ Classifier: Intended Audience :: Developers
13
+ Classifier: Intended Audience :: Manufacturing
14
+ Classifier: Operating System :: Microsoft :: Windows
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Topic :: Software Development :: Libraries
17
+ Requires-Python: >=3.10
18
+ Description-Content-Type: text/markdown
19
+
20
+ # gxw3call
21
+
22
+ Drive Mitsubishi Electric GX Works3 from Python through its Open Interface
23
+ (`GXW3Call.dll`): create projects, import hardware parameters and PLCopen
24
+ XML, rebuild, export, run the simulator and read or write devices, without
25
+ the GX Works3 window.
26
+
27
+ The interface is not documented by the vendor. Every one of its 302 methods
28
+ can be called here, and what is known about each one comes from real calls,
29
+ recorded in [docs/API.md](docs/API.md).
30
+
31
+ Not affiliated with or endorsed by Mitsubishi Electric. GX Works3 and MELSEC
32
+ are trademarks of Mitsubishi Electric Corporation.
33
+
34
+ ## Requirements
35
+
36
+ - Windows with GX Works3 installed (tested with 1.123D). `GXW3Call.dll` comes
37
+ with the standard installation.
38
+ - Python 3.10 or later, any bitness.
39
+ - A 32-bit Python 3.10+ for the worker process. The DLL is a 32-bit
40
+ in-process COM server, so the package starts a 32-bit worker and talks to
41
+ it over a local socket. The easiest way to get one:
42
+
43
+ ```
44
+ uv python install cpython-3.12-windows-x86
45
+ ```
46
+
47
+ It is found automatically; set `GXW3CALL_PYTHON32` to use another
48
+ interpreter.
49
+
50
+ ## Install
51
+
52
+ ```
53
+ pip install gxw3call
54
+ ```
55
+
56
+ or `uv add gxw3call`.
57
+
58
+ ## Usage
59
+
60
+ ### Build a project from parts
61
+
62
+ ```python
63
+ from gxw3call.client import Gx
64
+
65
+ with Gx() as gx:
66
+ project = gx.create_project(r'C:\work\new.gx3', 'R16')
67
+ try:
68
+ project.import_plc_files(r'C:\work\prm') # $MELPRJ$\SYSTEM/CPU/UNIT.PRM
69
+ project.import_xml(r'C:\work\ladder.xml') # PLCopen XML
70
+ errors, warnings = project.rebuild()
71
+ print(project.hardware(), project.pou_names())
72
+ project.save()
73
+ finally:
74
+ project.close()
75
+ ```
76
+
77
+ - Order matters: create, PRM files, XML, rebuild. An XML imported before the
78
+ PRM files arrives only in part.
79
+ - `import_plc_files` takes PRM bytes as stored inside a `.gx3`.
80
+ - CPU names are the ones GX uses (`R16`, `R32EN`, `FX5U`, `L04H`);
81
+ `gx.plc_types()` lists them.
82
+ - [examples/build_from_parts.py](examples/build_from_parts.py) runs this flow
83
+ and compares the instruction list with the source project.
84
+
85
+ ### Any method
86
+
87
+ ```python
88
+ from gxw3call.api import Api
89
+ from gxw3call.client import Gx
90
+
91
+ with Gx() as gx:
92
+ api = Api(gx)
93
+ out = api.project.open_project(r'C:\work\a.gx3', 180, 2, 0)
94
+ call_id = out['call_id']
95
+ try:
96
+ print(api.project.get_plc_type_string(call_id)['plc_type_string'])
97
+ print(api.project.get_pou_names(call_id, 0)['names']['value'])
98
+ finally:
99
+ api.project.close_project(call_id, 0)
100
+ ```
101
+
102
+ Method and argument names are snake_case with the Hungarian prefix dropped
103
+ (`bstrProjectPath` becomes `project_path`, `lplReturnCode` becomes
104
+ `return_code`); every docstring lists the original names. A docstring that
105
+ starts with "Measured" records what real calls showed; "Not measured" means
106
+ only the signature is known. Struct arguments take a dict (decoded from a
107
+ previous call or built by hand) or a hex string.
108
+
109
+ ## Things to know
110
+
111
+ - A return code of 0 does not prove success, and some calls work with a
112
+ non-zero code. Read results back.
113
+ - `lUserInterfaceMode` 2 runs GX hidden. 0 and 1 show a window that stays
114
+ open after the project is closed.
115
+ - Each opened project starts its own GX process (5 to 9 seconds). Close
116
+ projects in `finally`; an open project keeps the process and the file lock.
117
+ - Struct sizes in the type library are not reliable: the native side uses
118
+ pack 1, and some methods write more than the declared size.
119
+ - Paths must use backslashes; arguments ending in `Path` or `Folder` are
120
+ normalised.
121
+
122
+ ## Repository layout
123
+
124
+ | Path | Contents |
125
+ | --- | --- |
126
+ | `src/gxw3call/client.py` | `Gx` (worker connection) and `Project` (measured calls) |
127
+ | `src/gxw3call/api.py` | all 302 methods, generated by `tools/gen_api.py` |
128
+ | `src/gxw3call/worker.py` | 32-bit worker: loads the DLL, calls through the vtable |
129
+ | `src/gxw3call/typelib.py` | signatures, pack 1 struct encode and decode |
130
+ | `src/gxw3call/data/` | type library dump of GX Works3 1.123D |
131
+ | `docs/API.md` | reference: every method and struct with measured results |
132
+ | `notes/` | measured results (source of the docstrings and the reference) |
133
+ | `tools/` | probes, catalog dump, generators, type library dump script |
134
+
135
+ ## Contributing measurements
136
+
137
+ Add what a call showed to `notes/measured.json`
138
+ (`{"Method": {"status": "works" | "fails" | "unclear", "note": "..."}}`),
139
+ then regenerate:
140
+
141
+ ```
142
+ python tools/gen_api.py
143
+ python tools/gen_doc.py
144
+ ```
145
+
146
+ `tools/probe_readonly.py` calls the read-only methods with default arguments;
147
+ `tools/probe_changes.py` calls methods on copies of a project and reports
148
+ which parts of the saved file changed. Run them only on copies. For another
149
+ GX Works3 version, dump the type library first:
150
+
151
+ ```
152
+ powershell -File tools\tlb_dump.ps1 "C:\Program Files (x86)\MELSOFT\GPPW3\GXW3Call.dll" | Out-File -Encoding utf8 src\gxw3call\data\GXW3Call_tlb.txt
153
+ ```
154
+
155
+ ## License
156
+
157
+ MIT
@@ -0,0 +1,138 @@
1
+ # gxw3call
2
+
3
+ Drive Mitsubishi Electric GX Works3 from Python through its Open Interface
4
+ (`GXW3Call.dll`): create projects, import hardware parameters and PLCopen
5
+ XML, rebuild, export, run the simulator and read or write devices, without
6
+ the GX Works3 window.
7
+
8
+ The interface is not documented by the vendor. Every one of its 302 methods
9
+ can be called here, and what is known about each one comes from real calls,
10
+ recorded in [docs/API.md](docs/API.md).
11
+
12
+ Not affiliated with or endorsed by Mitsubishi Electric. GX Works3 and MELSEC
13
+ are trademarks of Mitsubishi Electric Corporation.
14
+
15
+ ## Requirements
16
+
17
+ - Windows with GX Works3 installed (tested with 1.123D). `GXW3Call.dll` comes
18
+ with the standard installation.
19
+ - Python 3.10 or later, any bitness.
20
+ - A 32-bit Python 3.10+ for the worker process. The DLL is a 32-bit
21
+ in-process COM server, so the package starts a 32-bit worker and talks to
22
+ it over a local socket. The easiest way to get one:
23
+
24
+ ```
25
+ uv python install cpython-3.12-windows-x86
26
+ ```
27
+
28
+ It is found automatically; set `GXW3CALL_PYTHON32` to use another
29
+ interpreter.
30
+
31
+ ## Install
32
+
33
+ ```
34
+ pip install gxw3call
35
+ ```
36
+
37
+ or `uv add gxw3call`.
38
+
39
+ ## Usage
40
+
41
+ ### Build a project from parts
42
+
43
+ ```python
44
+ from gxw3call.client import Gx
45
+
46
+ with Gx() as gx:
47
+ project = gx.create_project(r'C:\work\new.gx3', 'R16')
48
+ try:
49
+ project.import_plc_files(r'C:\work\prm') # $MELPRJ$\SYSTEM/CPU/UNIT.PRM
50
+ project.import_xml(r'C:\work\ladder.xml') # PLCopen XML
51
+ errors, warnings = project.rebuild()
52
+ print(project.hardware(), project.pou_names())
53
+ project.save()
54
+ finally:
55
+ project.close()
56
+ ```
57
+
58
+ - Order matters: create, PRM files, XML, rebuild. An XML imported before the
59
+ PRM files arrives only in part.
60
+ - `import_plc_files` takes PRM bytes as stored inside a `.gx3`.
61
+ - CPU names are the ones GX uses (`R16`, `R32EN`, `FX5U`, `L04H`);
62
+ `gx.plc_types()` lists them.
63
+ - [examples/build_from_parts.py](examples/build_from_parts.py) runs this flow
64
+ and compares the instruction list with the source project.
65
+
66
+ ### Any method
67
+
68
+ ```python
69
+ from gxw3call.api import Api
70
+ from gxw3call.client import Gx
71
+
72
+ with Gx() as gx:
73
+ api = Api(gx)
74
+ out = api.project.open_project(r'C:\work\a.gx3', 180, 2, 0)
75
+ call_id = out['call_id']
76
+ try:
77
+ print(api.project.get_plc_type_string(call_id)['plc_type_string'])
78
+ print(api.project.get_pou_names(call_id, 0)['names']['value'])
79
+ finally:
80
+ api.project.close_project(call_id, 0)
81
+ ```
82
+
83
+ Method and argument names are snake_case with the Hungarian prefix dropped
84
+ (`bstrProjectPath` becomes `project_path`, `lplReturnCode` becomes
85
+ `return_code`); every docstring lists the original names. A docstring that
86
+ starts with "Measured" records what real calls showed; "Not measured" means
87
+ only the signature is known. Struct arguments take a dict (decoded from a
88
+ previous call or built by hand) or a hex string.
89
+
90
+ ## Things to know
91
+
92
+ - A return code of 0 does not prove success, and some calls work with a
93
+ non-zero code. Read results back.
94
+ - `lUserInterfaceMode` 2 runs GX hidden. 0 and 1 show a window that stays
95
+ open after the project is closed.
96
+ - Each opened project starts its own GX process (5 to 9 seconds). Close
97
+ projects in `finally`; an open project keeps the process and the file lock.
98
+ - Struct sizes in the type library are not reliable: the native side uses
99
+ pack 1, and some methods write more than the declared size.
100
+ - Paths must use backslashes; arguments ending in `Path` or `Folder` are
101
+ normalised.
102
+
103
+ ## Repository layout
104
+
105
+ | Path | Contents |
106
+ | --- | --- |
107
+ | `src/gxw3call/client.py` | `Gx` (worker connection) and `Project` (measured calls) |
108
+ | `src/gxw3call/api.py` | all 302 methods, generated by `tools/gen_api.py` |
109
+ | `src/gxw3call/worker.py` | 32-bit worker: loads the DLL, calls through the vtable |
110
+ | `src/gxw3call/typelib.py` | signatures, pack 1 struct encode and decode |
111
+ | `src/gxw3call/data/` | type library dump of GX Works3 1.123D |
112
+ | `docs/API.md` | reference: every method and struct with measured results |
113
+ | `notes/` | measured results (source of the docstrings and the reference) |
114
+ | `tools/` | probes, catalog dump, generators, type library dump script |
115
+
116
+ ## Contributing measurements
117
+
118
+ Add what a call showed to `notes/measured.json`
119
+ (`{"Method": {"status": "works" | "fails" | "unclear", "note": "..."}}`),
120
+ then regenerate:
121
+
122
+ ```
123
+ python tools/gen_api.py
124
+ python tools/gen_doc.py
125
+ ```
126
+
127
+ `tools/probe_readonly.py` calls the read-only methods with default arguments;
128
+ `tools/probe_changes.py` calls methods on copies of a project and reports
129
+ which parts of the saved file changed. Run them only on copies. For another
130
+ GX Works3 version, dump the type library first:
131
+
132
+ ```
133
+ powershell -File tools\tlb_dump.ps1 "C:\Program Files (x86)\MELSOFT\GPPW3\GXW3Call.dll" | Out-File -Encoding utf8 src\gxw3call\data\GXW3Call_tlb.txt
134
+ ```
135
+
136
+ ## License
137
+
138
+ MIT