Skip to content

Commit 1e8a44a

Browse files
hansuhansu
committed
docs: Python HAL module
1 parent 56883b9 commit 1e8a44a

8 files changed

Lines changed: 244 additions & 204 deletions

File tree

‎docs/po4a.cfg‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,7 @@
3939
[type: AsciiDoc_def] src/config/lathe-config.adoc $lang:src/$lang/config/lathe-config.adoc
4040
[type: AsciiDoc_def] src/config/moveoff.adoc $lang:src/$lang/config/moveoff.adoc
4141
[type: AsciiDoc_def] src/config/pncconf.adoc $lang:src/$lang/config/pncconf.adoc
42+
[type: AsciiDoc_def] src/config/python-hal-interface.adoc $lang:src/$lang/config/python-hal-interface.adoc
4243
[type: AsciiDoc_def] src/config/python-interface.adoc $lang:src/$lang/config/python-interface.adoc
4344
[type: AsciiDoc_def] src/config/stepconf.adoc $lang:src/$lang/config/stepconf.adoc
4445
[type: AsciiDoc_def] src/config/stepper.adoc $lang:src/$lang/config/stepper.adoc

‎docs/src/Master_Documentation.adoc‎

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -79,6 +79,7 @@ include::config/stepper.adoc[]
7979

8080
include::config/stepper-diagnostics.adoc[]
8181

82+
include::gui/filter-programs.adoc[]
8283

8384
:leveloffset: 1
8485
= HAL (Hardware Abstraction Layer)
@@ -104,6 +105,10 @@ include::hal/comp.adoc[]
104105

105106
include::hal/haltcl.adoc[]
106107

108+
include::gui/halui.adoc[]
109+
110+
include::hal/halui-examples.adoc[]
111+
107112
include::hal/halmodule.adoc[]
108113

109114
include::hal/canonical-devices.adoc[]
@@ -284,14 +289,10 @@ include::gui/qtvcp-development.adoc[]
284289
:leveloffset: 2
285290
include::gui/panelui.adoc[]
286291

287-
include::gui/filter-programs.adoc[]
288-
289-
include::gui/halui.adoc[]
290-
291-
include::hal/halui-examples.adoc[]
292-
293292
include::config/python-interface.adoc[]
294293

294+
include::config/python-hal-interface.adoc[]
295+
295296
include::gui/gstat.adoc[]
296297

297298
include::gui/vismach.adoc[]

‎docs/src/Submakefile‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,7 @@ DOC_SRCS_EN := \
5353
config/lathe-config.adoc \
5454
config/moveoff.adoc \
5555
config/pncconf.adoc \
56+
config/python-hal-interface.adoc \
5657
config/python-interface.adoc \
5758
config/stepconf.adoc \
5859
config/stepper-diagnostics.adoc \

‎docs/src/config/python-hal-interface.adoc‎

Lines changed: 221 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,221 @@
1+
:lang: en
2+
:toc:
3+
4+
[[cha:python-hal-interface]]
5+
= The HAL Python module
6+
7+
:ini: {basebackend@docbook:'':ini}
8+
:hal: {basebackend@docbook:'':hal}
9+
:ngc: {basebackend@docbook:'':ngc}
10+
11+
This documentation describes the `hal` python module, which provides
12+
a Python API for creating and accessing HAL pins and signals.
13+
14+
15+
== Basic usage
16+
17+
18+
[source,python]
19+
----
20+
#!/usr/bin/env python3
21+
import hal, time
22+
h = hal.component("passthrough")
23+
h.newpin("in", hal.HAL_FLOAT, hal.HAL_IN)
24+
h.newpin("out", hal.HAL_FLOAT, hal.HAL_OUT)
25+
h.ready()
26+
----
27+
28+
== Functions
29+
30+
31+
*component*:: +
32+
The component itself is created by a call to the constructor `hal.component`.
33+
The arguments are the HAL component name and (optionally) the
34+
prefix used for pin and parameter names. If the prefix is not
35+
specified, the component name is used. +
36+
.Example
37+
[source,python]
38+
----
39+
h = hal.component("passthrough")
40+
----
41+
42+
*newpin*:: +
43+
Create new pin. +
44+
Arguments: pin name suffix, pin type, and pin direction. For
45+
parameters, the arguments are: parameter name suffix, parameter type,
46+
and parameter direction. +
47+
.Example:
48+
[source,python]
49+
----
50+
h.newpin("in", hal.HAL_FLOAT, hal.HAL_IN)
51+
----
52+
53+
54+
*ready* ::
55+
Tells the HAL system the component is initialized. Locks out adding pins.
56+
57+
*unready* ::
58+
Allows a component to add pins after 'ready()' has been called.
59+
One should call 'ready()' on the component after.
60+
61+
*component_exists* ::
62+
Does the specified component exist at this time.
63+
64+
.Example
65+
----
66+
hal.component_exists("testpanel")
67+
----
68+
69+
*component_is_ready* ::
70+
Is the specified component ready at this time.
71+
72+
.Example
73+
----
74+
hal.component_is_ready("testpanel")
75+
----
76+
77+
*get_msg_level* ::
78+
Get the current Realtime msg level.
79+
80+
*set_msg_level* ::
81+
Set the current Realtime msg level.
82+
used for debugging information.
83+
84+
*connect* ::
85+
Connect a pin to a signal.
86+
87+
.Example
88+
----
89+
hal.connect("pinname","signal_name")
90+
----
91+
92+
*disconnect* ::
93+
Disconnect a pin from a signal.
94+
95+
.Example
96+
----
97+
hal.disconnect("pinname")
98+
----
99+
100+
*get_value* ::
101+
Read a pin, param, or signal directly.
102+
103+
.Example
104+
[source,python]
105+
----
106+
value = hal.get_value("iocontrol.0.emc-enable-in")
107+
----
108+
109+
*get_info_pins()* ::
110+
Returns a list of dicts of all system pins.
111+
112+
[source,python]
113+
----
114+
listOfDicts = hal.get_info_pins()
115+
pinName1 = listOfDicts[0].get('NAME')
116+
pinValue1 = listOfDicts[0].get('VALUE')
117+
pinType1 = listOfDicts[0].get('TYPE')
118+
pinDirection1 = listOfDicts[0].get('DIRECTION')
119+
----
120+
121+
*get_info_signals()* ::
122+
Returns a list of dicts of all system signals.
123+
124+
[source,python]
125+
----
126+
listOfDicts = hal.get_info_signals()
127+
signalName1 = listOfDicts[0].get('NAME')
128+
signalValue1 = listOfDicts[0].get('VALUE')
129+
driverPin1 = listOfDicts[0].get('DRIVER')
130+
----
131+
132+
*get_info_params()* ::
133+
Returns a list of dicts of all system parameters.
134+
135+
[source,python]
136+
----
137+
listOfDicts = hal.get_info_params()
138+
paramName1 = listOfDicts[0].get('NAME')
139+
paramValue1 = listOfDicts[0].get('VALUE')
140+
paramDirection1 = listOfDicts[0].get('DIRECTION')
141+
----
142+
143+
*new_sig* ::
144+
Create a new signal of the type specified.
145+
146+
.Example
147+
[source,python]
148+
----
149+
hal.new_sig("signalname",hal.HAL_BIT)
150+
----
151+
152+
*pin_has_writer* ::
153+
Does the specified pin have a driving pin connected. +
154+
Returns True or False.
155+
156+
----
157+
h.in.pin_has_writer()
158+
----
159+
160+
*get_name* ::
161+
Get the HAL object name. +
162+
Return a string.
163+
164+
----
165+
h.in.get_name()
166+
----
167+
168+
*get_type* ::
169+
Get the HAL object's type. +
170+
Returns an integer.
171+
172+
----
173+
h.in.get_type()
174+
----
175+
176+
*get_dir* ::
177+
Get the HAL object direction type. +
178+
Returns an integer.
179+
180+
----
181+
h.in.get_dir()
182+
----
183+
184+
*get* ::
185+
Get the HAL object value.
186+
187+
----
188+
h.in.get()
189+
----
190+
191+
*set* ::
192+
Set the HAL object value.
193+
194+
----
195+
h.out.set(10)
196+
----
197+
198+
*is_pin* ::
199+
Is the object a pin or parameter? +
200+
Returns True or False.
201+
202+
----
203+
h.in.is_pin()
204+
----
205+
206+
*sampler_base* ::
207+
TODO
208+
209+
*stream_base* ::
210+
TODO
211+
212+
*stream* ::
213+
TODO
214+
215+
*set_p* ::
216+
Set a pin value of any pin in the HAL system.
217+
218+
.Example
219+
----
220+
hal.set_p("pinname","10")
221+
----

‎docs/src/config/python-interface.adoc‎

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
:toc:
33

44
[[cha:python-interface]]
5-
= Python Interface
5+
= The LinuxCNC Python module
66

77
:ini: {basebackend@docbook:'':ini}
88
:hal: {basebackend@docbook:'':hal}
@@ -15,8 +15,7 @@ a Python API for talking to LinuxCNC.
1515
constants are located in src/emc/usr_intf/axis/extensions/emcmodule.cc
1616
////
1717

18-
== The `linuxcnc` Python module
19-
18+
== Introduction
2019
User interfaces control LinuxCNC activity by sending
2120
NML messages to the LinuxCNC task controller, and monitor results by
2221
observing the LinuxCNC status structure, as well as the error reporting channel.
@@ -510,7 +509,7 @@ For each joint, the following dictionary keys are available:
510509
current velocity.
511510

512511
[[sec:the-spindle-dictionary]]
513-
== The `spindle` dictionary
512+
=== The `spindle` dictionary
514513

515514
*brake*:: '(returns integer)' -
516515
value of the spindle brake flag.

‎docs/src/gui/gstat.adoc‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
:toc:
33

44
[[cha:gstat]]
5-
= GStat
5+
= GStat Python Module
66

77
== Intro
88

0 commit comments

Comments
 (0)