Skip to content

docs: Update to reflect the HAL API changes #4596

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
grandixximo merged 1 commit into from
Sep 29, 2026
Merged

docs: Update to reflect the HAL API changes #4596

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/src/code/code-notes.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1269,7 +1269,7 @@ emcioStatus.tool.pocketPrepped::

emcioStatus.tool.toolInSpindle::
Tool number of the tool currently installed in the spindle.
Exported on the HAL pin +iocontrol.0.tool-number+ (s32).
Exported on the HAL pin +iocontrol.0.tool-number+ (sint).

emcioStatus.tool.toolTable[]::
An array of +CANON_TOOL_TABLE+ structures, +CANON_POCKETS_MAX+ long.
Expand Down
6 changes: 3 additions & 3 deletions docs/src/common/glossary.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -161,7 +161,7 @@ Feedrate Override::
anything else that requires the feed rate to be "tweaked".

Floating Point Number::
A number that has a decimal point. (12.300) In HAL it is known as float.
A number that has a decimal point. (12.300) In HAL it is known as real.

G-code::
(((G-code))) The generic term used to refer to the most
Expand Down Expand Up @@ -321,7 +321,7 @@ Servo Loop::

Signed Integer::
(((Signed Integer))) A whole number that can have a positive or negative sign.
In HAL it is usually a <<sub:hal-s32,s32>>, but could be also a <<sub:hal-s64,s64>>.
In HAL it is a <<sub:hal-sint,sint>>.

Spindle::
(((spindle))) The part of a machine tool that spins
Expand Down Expand Up @@ -364,7 +364,7 @@ Units::

Unsigned Integer::
(((Unsigned Integer))) A whole number that has no sign.
In HAL it is usually a <<sub:hal-u32,u32>> but could be also a <<sub:hal-u64,u64>>.
In HAL it is a <<sub:hal-uint,uint>>.

World Coordinates::
(((world coordinates))) This is the absolute
Expand Down
196 changes: 98 additions & 98 deletions docs/src/config/core-components.adoc
View file
Open in desktop

Large diffs are not rendered by default.

12 changes: 6 additions & 6 deletions docs/src/config/ini-homing.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -382,17 +382,17 @@ Example: Synced joints 0,1 using negative sequence (-1) for synchronized homing
[source,hal]
----
loadrt mux2 names=home_sequence_mux
loadrt conv_float_s32 names=home_sequence_s32
loadrt conv_real_sint names=home_sequence_sint
setp home_sequence_mux.in0 -1
setp home_sequence_mux.in1 1
addf home_sequence_mux servo-thread
addf home_sequence_s32 servo-thread
addf home_sequence_sint servo-thread
...
net home_seq_float <= home_sequence_mux.out
net home_seq_float => home_sequence_s32.in
net home_seq_s32 <= home_sequence_s32.out
net home_seq_s32 => ini.0.home_sequence
net home_seq_s32 => ini.1.home_sequence
net home_seq_float => home_sequence_sint.in
net home_seq_sint <= home_sequence_sint.out
net home_seq_sint => ini.0.home_sequence
net home_seq_sint => ini.1.home_sequence
...
# allow_jjog: pin created by a virtual panel or hardware switch
net hsequence_select <= allow_jjog
Expand Down
8 changes: 4 additions & 4 deletions docs/src/config/mtconnect.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -64,10 +64,10 @@ curl http://localhost:5000/assets

Loaded from a HAL file, the component exposes pins you can link:

* `mtconnect-agent.enable` (bit, in) - gate polling and publishing.
* `mtconnect-agent.active` (bit, out) - TRUE while polling and serving.
* `mtconnect-agent.connected` (bit, out) - TRUE while the MQTT broker link is up.
* `mtconnect-agent.heartbeat` (u32, out) - increments each poll.
* `mtconnect-agent.enable` (bool, in) - gate polling and publishing.
* `mtconnect-agent.active` (bool, out) - TRUE while polling and serving.
* `mtconnect-agent.connected` (bool, out) - TRUE while the MQTT broker link is up.
* `mtconnect-agent.heartbeat` (uint, out) - increments each poll.

== Exposing custom HAL pins

Expand Down
53 changes: 25 additions & 28 deletions docs/src/config/python-hal-interface.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,10 +55,6 @@ The old defined constants are still supported for backwards compatibility.
.Example:
[source,python]
----
# Old (deprecated) style:
comp.newpin("in-a", hal.HAL_FLOAT, hal.HAL_IN)

# New style:
comp.newpin("in-a", hal.Type.REAL, hal.Dir.IN)
----

Expand All @@ -71,22 +67,22 @@ The `hal.Type` enum is used to specify the type of pin, parameter and signal:
* `hal.Type.UINT` - An unsigned quantity with range 0...+2^64^-1
* `hal.Type.REAL` - A floating point quantity of range &#177;1.80×10^308^
* `hal.Type.PORT` - An opaque quantity representing a communication channel (pins only)
* `hal.Type.S32` - A signed quantity with range -2^31^...+2^31^-1 (see notes below)
* `hal.Type.U32` - An unsigned quantity with range 0...+2^32^-1 (see notes below)

There are aliases in the `hal.Type` enum for all types with the `HAL_` prefix (e.g. `hal.Type.HAL_BOOL`, etc.).

[NOTE]
====
The constants previously used (`hal.HAL_BIT`, `hal.HAL_FLOAT`, etc.) are still available.
The constants previously used (`hal.HAL_BIT`, `hal.HAL_FLOAT`, etc.) are deprecated and emit a warning.
You should upgrade your code to use the enumerated types with the new names instead.
====

[IMPORTANT]
====
The 32-bit types will soon be replaced by 64-bit types.
The names will remain for some time, but they will map to the larger type automatically.
The `S32` and `U32` names will then no longer be unique and the range will be larger.
[source,python]
----
# Old (deprecated) style:
comp.newpin("in-a", hal.HAL_FLOAT, hal.HAL_IN)

# New style:
comp.newpin("in-a", hal.Type.REAL, hal.Dir.IN)
----
====

==== HAL direction
Expand All @@ -104,13 +100,16 @@ Also the direction enums are available with the `HAL_` prefix (like `hal.Dir.HAL

==== Old style HAL constants (deprecated)

Old style constants (deprecated):
`hal.HAL_BIT`, `hal.HAL_S32`, `hal.HAL_U32`, `hal.HAL_S64`, `hal.HAL_U64`, `hal.HAL_FLOAT`, `hal.HAL_PORT`.
Old style constants (deprecated, please use `hal.Type.XXXX`):
`hal.HAL_BOOL`, `hal.HAL_SINT`, `hal.HAL_UINT`, `hal.HAL_REAL`, `hal.HAL_PORT`.
Comment thread
BsAtHome marked this conversation as resolved.

Deprecated constants (replaced with new names, please use `hal.Type.XXXX`):
`hal.HAL_BIT`, `hal.HAL_S64`, `hal.HAL_U64`, `hal.HAL_FLOAT`.

@grandixximo grandixximo Sep 29, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The deprecated list covers HAL_BIT/HAL_FLOAT/HAL_S64/HAL_U64, but the hal.py getattr shim also accepts HAL_S32 and HAL_U32 (with a 'no longer supported' FutureWarning). Add them here for completeness?

@BsAtHome BsAtHome Sep 29, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I considered it, but rejected it. The base code no longer has them and the shim replaces them with UINT/SINT. The warning is different for these than for the others. In python we can just pretend because it does not really care about the integer size. Besides, there is a (very) large list of things you need to do when migrating and this doc is just a tiny fraction. Better put that in the "upgrade" doc(s) is my thinking.


Old style deprecated pin direction constants (deprecated):
Old style deprecated pin direction constants (deprecated, please use `hal.Dir.YYY`):
`hal.HAL_IN`, `hal.HAL_OUT`, `hal.HAL_IO`.

Old style deprecated parameter access constants (deprecated):
Old style deprecated parameter access constants (deprecated, please use `hal.Dir.YYY`):
`hal.HAL_RO`, `hal.HAL_RW`.

[[halconstantsmsg]]
Expand Down Expand Up @@ -271,8 +270,8 @@ Textual representations are case insensitive.
.Example:
[source,python]
----
hal.set_p("mycomp.0.bit", True)
hal.set_p("mycomp.0.float", 99.99)
hal.set_p("mycomp.0.bool", True)
hal.set_p("mycomp.0.real", 99.99)
----

hal.set_s(_name_:string, _value_:mixed)::
Expand Down Expand Up @@ -429,12 +428,10 @@ Each data sample may contain up to twenty (20) values.
The type of the values in a sample must be configured and specified in a type string.
anchor:type-string[]The type string consists of the following characters (case insensitive):

* `b` - Boolean
* `s` - Signed 32-bit
* `u` - Unsigned 32-bit
* `l` - Signed 64-bit
* `k` - Unsigned 64-bit
* `f` - Floating point (real)
* `b` - Boolean (bool)
* `s`, `l` - Signed 64-bit (sint)
* `u`, `k` - Unsigned 64-bit (uint)
* `f`, `r` - Floating point (real)

Two components are available, 'streamer' and 'sampler'.
The 'streamer' component writes a set of pins from non-real-time data pushed into a stream.
Expand Down Expand Up @@ -576,7 +573,7 @@ result = hal.query.pin("my.pin.name")
result = {
"haltype" : "pin",
"name" : "my.pin.name",
"type" : hal.Type.<BOOL,REAL,SINT,UINT,PORT,S32,U32>,
"type" : hal.Type.<BOOL,REAL,SINT,UINT,PORT>,
"dir" : hal.Dir.<IN,OUT,IO>,
"value" : <bool, int or float>,
"alias" : "alias.name"|None,
Expand All @@ -597,7 +594,7 @@ result = hal.query.param("my.param.name")
result = {
"haltype" : "parameter",
"name" : "my.param.name",
"type" : hal.Type.<BOOL,REAL,SINT,UINT,S32,U32>,
"type" : hal.Type.<BOOL,REAL,SINT,UINT>,
"dir" : hal.Dir.<RO,WR>,
"value" : <bool, int or float>,
"alias" : "alias.name"|None,
Expand All @@ -617,7 +614,7 @@ result = hal.query.signal("my.signal.name")
result = {
"haltype" : "signal",
"name" : "my.signal.name",
"type" : hal.Type.<BOOL,REAL,SINT,UINT,PORT,S32,U32>,
"type" : hal.Type.<BOOL,REAL,SINT,UINT,PORT>,
"value" : <bool, int or float>,
"writers" : <int>,
"readers" : <int>,
Expand Down
Loading
Loading