Skip to content

Commit 02a597e

Browse files
hansuhansu
authored
Merge pull request #2293 from hansu/docs-move-halmodule
docs: move halmodule + change title
2 parents f15826f + 3879ee4 commit 02a597e

9 files changed

Lines changed: 313 additions & 313 deletions

File tree

‎docs/po4a.cfg‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,7 @@
4040
[type: AsciiDoc_def] src/config/lathe-config.adoc $lang:src/$lang/config/lathe-config.adoc
4141
[type: AsciiDoc_def] src/config/moveoff.adoc $lang:src/$lang/config/moveoff.adoc
4242
[type: AsciiDoc_def] src/config/pncconf.adoc $lang:src/$lang/config/pncconf.adoc
43+
[type: AsciiDoc_def] src/config/python-hal-interface.adoc $lang:src/$lang/config/python-hal-interface.adoc
4344
[type: AsciiDoc_def] src/config/python-interface.adoc $lang:src/$lang/config/python-interface.adoc
4445
[type: AsciiDoc_def] src/config/stepconf.adoc $lang:src/$lang/config/stepconf.adoc
4546
[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
@@ -54,6 +54,7 @@ DOC_SRCS_EN := \
5454
config/lathe-config.adoc \
5555
config/moveoff.adoc \
5656
config/pncconf.adoc \
57+
config/python-hal-interface.adoc \
5758
config/python-interface.adoc \
5859
config/stepconf.adoc \
5960
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/gladevcp.adoc‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3032,6 +3032,42 @@ def get_handlers(halcomp,builder,useropts):
30323032
return [HandlerClass(halcomp,builder,useropts)]
30333033
----
30343034

3035+
=== Value-changed callback with hal_glib
3036+
3037+
GladeVCP uses the hal_glib library, which can be used to connect a "watcher" signal on a HAL input pin. +
3038+
This signal can be used to register a function to call when the HAL pin changes state. +
3039+
3040+
One must import the `hal_glib` and the `hal` modules:
3041+
3042+
[source,python]
3043+
----
3044+
import hal_glib
3045+
import hal
3046+
----
3047+
3048+
Then make a pin and connect a 'value-changed' (the watcher) signal to a function call:
3049+
3050+
[source,python]
3051+
----
3052+
class HandlerClass:
3053+
def __init__(self, halcomp,builder,useropts):
3054+
self.example_trigger = hal_glib.GPin(halcomp.newpin('example-trigger', hal.HAL_BIT, hal.HAL_IN))
3055+
self.example_trigger.connect('value-changed', self._on_example_trigger_change)
3056+
----
3057+
3058+
And have a function to be called:
3059+
3060+
[source,python]
3061+
----
3062+
def _on_example_trigger_change(self,pin,userdata=None):
3063+
print("pin value changed to: {}".format(pin.get()))
3064+
print("pin name= {}".format(pin.get_name()))
3065+
print("pin type= {}".format(pin.get_type()))
3066+
3067+
# this can be called outside the function
3068+
self.example_trigger.get()
3069+
----
3070+
30353071
=== Examples, and rolling your own GladeVCP application
30363072

30373073
Visit `linuxcnc_root_directory/configs/apps/gladevcp` for running

‎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)