HAL-pythonmodulen

Returns a boolean to indicate whether hal is initialized. This methods should always return True because the HAL module is automatically initialized at import time.

import hal

assert hal.is_initialized(), "fatal: HAL failed to initialize at import"

Returns the type of the running realtime system. Might return hal.RTType.UNINITIALIZED if rtapi_app is not running. See realtime type constants. See also LinuxCNC Realtime check.

Returns a boolean to indicate whether or not the specified component exist at this time.

Returns a boolean to indicate whether or not the specified component is in the ready state. Also returns False if the component does not exist.

if not hal.component_is_ready("testpanel"):
    compmsg = "ready" if hal.component_exists("testpanel") else "loaded"
    print("Expected component 'testpanel' to be {}".format(compmsg))
    os.exit(1)

Set the message level that controls the amount of information being printed and forwarded from real-time components. The lvl argument must be one of the message constants.

Return the current message level. See hal.set_msg_level() and message constants for list of possible returned values.

Create a new signal (net) called name. The signal can carry information of type content. Returns True on success.

if not hal.new_sig("signalname", hal.Type.BOOL):
    ...handle error...

Connect the pin pinname to signal signame. Both signal and pin must exist and both pin and signal must be of the same type. Returns True on success.

if not hal.connect("mycomp.pinname", "signalname"):
    ...handle error...

Disconnect the pin pinname from signal signame. Both signal and pin must exist. Returns True on success.

if not hal.disconnect("mycomp.pinname"):
    ...handle error...

Returns True if pin with name pinname is attached to a signal and there is at least one writer. Otherwise, False is returned.

if hal.pin_has_writer("mycomp.0.pin.02"):
    print("Pin has writer")
else:
    print("Pin has no writer or no signal attached")

Sets the pin or param called name to value. The name is the full name of the pin or param. The search order is pin names first, then parameter names.
Throws a RuntimeError exception if the name is not found.
The type of value depends on the type of the pin or param. Integer scalar types may use integers or a textual representation of an integer to set the value. Floating point type may use both integer, floating point and textual representation thereof to set the value. Booleans accept True, False and map the integer value zero (0) to false. The exact floating point value of zero (0.0) also maps for false. Booleans may also be of text "0", "1", "on", "off", "true", "false", "yes" or "no". Textual representations are case insensitive.

hal.set_p("mycomp.0.bit", True)
hal.set_p("mycomp.0.float", 99.99)

Sets the signal (net) called name to value. The same rules for value apply to set_s() as to set_p().

The set_s() method has one special case when the signal is of type hal.Type.PORT and it is fully connected. In that case, the call uses the value to set the port’s queue size and it must be a positive integer. See below on configuring a port.

Returns the value of the pin or param with name. If name refers to a pin and that pin is connected, then the connected signal’s value is returned. Boolean types return True or False. Integer scalar types return an integer. Floating point types return a float. The value None is returned if no pin or param is found by that name.

Returns the value of the signal with name. Boolean types return True or False. Integer scalar types return an integer. Floating point types return a float. The value None is returned if no signal is found by that name.

Returns the value of the pin, param or signal with name, searched in that order. Boolean types return True or False. Integer scalar types return an integer. Floating point types return a float. A RuntimeError exception is thrown if no pin, param or signal is found by that name.

value = hal.get_value("iocontrol.0.emc-enable-in")

DEPRECATED: replaced by hal.query.pins().
Returns a list of dictionary tuples as in {"NAME":"pinname", "VALUE":<bool|int|float>, "TYPE":<int>, "DIRECTION":<int>}.

# Old style (deprecated):
for i in hal.get_info_pins():
    print(i['NAME'], i['TYPE'], i['DIRECTION'], i['VALUE'])

# New style (see hal.query sub-module below):
for pinname,pindetail in hal.query.pins().items():
    print(pinname, pindetail['type'], pindetail['dir'], pindetail['value'])

DEPRECATED: replaced by hal.query.params().
Returns a list of dictionary tuples as in {"NAME":"paramname", "VALUE":<bool|int|float>, "TYPE":<int>, "DIRECTION":<int>}.

DEPRECATED: replaced by hal.query.signals().
Returns a list of dictionary tuples as in {"NAME":"signame", "VALUE":<bool|int|float>, "TYPE":<int>, "DRIVER":"name"|None}.

# New style (see hal.query sub-module below)
for signame,sigdetail in hal.query.signals().items():
    print(signame, sigdetail['type'], sigdetail['value'], sigdetail['driver'])

The component itself is created by a call to the constructor hal.component. The arguments are the HAL component name and (optionally) the prefix used for pin and param names. If the prefix is not specified, the component name is used.

comp = hal.component("passthrough")

Create new pin with actual name prefix.__name__. The pin type must be one of the types described above. The io specifies the direction of the pin. Throws a ValueError exception if name already exists.

p_in = comp.newpin("in", hal.Type.FLOAT, hal.Dir.IN)

Create new parameter with actual name prefix.__name__. The pin type argument must be one of the types described above. Parameters cannot be of type hal.Type.PORT. The access argument specifies the allowed param access. Throws a ValueError exception if name already exists.

p_bloop = comp.newparam("bloop", hal.Type.FLOAT, hal.Dir.RO)

Return the pin or param item object name previously created with comp.newpin() or comp.newparam(). Throws an AttributeError exception if no pin or param named name is found. Use comp.getpin() or comp.getparam() to find the specific type.

Return the pin item object pinname previously created with comp.newpin(). Throws an AttributeError exception if no pin names pinname is found. A param called pinname will not be found and throws an exception. Use comp.getitem() to find either.

Return the param item object paramname previously created with copm.newparam(). Throws an AttributeError exception if no pin names paramname is found. A pin called paramname will not be found and throws an exception. Use comp.getitem() to find either.

Returns a dictionary all pin and param names and their values. The pin or param name is the dictionary key.

Tells the HAL system the component is initialized. Locks out adding pins.

Allows a component to add pins after ready() has been called. One should call ready() on the component when done.

Returns the current component’s prefix used when creating pins and params. It defaults to the component name when not set in the constructor or by setprefix.

Set the prefix used when creating pins and params. The prefix is used to create pins and params called __prefix__.name and defaults to the components name.

The sampler component’s (sampler.c) shared memory ID for stream communication.

The streamer component’s (streamer.c) shared memory ID for stream communication.

Create a stream for the component comp using the shared memory identifier key. The stream’s queue size is allocated for depth samples of typestr format. See the type string list for type meaning.

Attach to a stream for the component comp where the shared memory location is identified by key. If the optional typestr is provided, then it will be checked against the existing stream’s configuration. See the type string list for type meaning.

Returns a tuple of sample data from the queue. None is returned if no samples were available.

Writes the sample argument to the stream queue. The sample must contain the correct number of elements and match the types (or be convertible) of the stream’s configuration. An IOError exception is thrown if the sample could not be written to the queue.

Returns True if there are samples available for reading in the stream queue or False if not.

Returns True if there is space available in the stream queue to hold more samples or False if not.

Returns the number of currently available samples for read in the queue.

Returns the queue size as set when the stream was created (and cannot be changed).

Return a bytes object with the format type string that was used to create the stream. See type string list for individual elements and type meaning.

Returns the number of times stream.read() was called when no samples were available from the queue.

Returns the number of times stream.write() was called when no samples could be stored in the queue.

The last successfully read sample ID number as counted by the stream functions.

Retrieve all information of the pin name. Returns None if the name was not found. Otherwise, returns a dictionary with the pin information:

result = hal.query.pin("my.pin.name")
result = {
    "haltype" : "pin",
    "name"    : "my.pin.name",
    "type"    : hal.Type.<BOOL,REAL,SINT,UINT,PORT,S32,U32>,
    "dir"     : hal.Dir.<IN,OUT,IO>,
    "value"   : <bool, int or float>,
    "alias"   : "alias.name"|None,
    "signal"  : "signal.name"|None,
    "comp"    : "component-name",
    "comp_id" : <int>
}

Retrieve all information of the parameter name. Returns None if the name was not found. Otherwise, returns a dictionary with the parameter information:

result = hal.query.param("my.param.name")
result = {
    "haltype" : "parameter",
    "name"    : "my.param.name",
    "type"    : hal.Type.<BOOL,REAL,SINT,UINT,S32,U32>,
    "dir"     : hal.Dir.<RO,WR>,
    "value"   : <bool, int or float>,
    "alias"   : "alias.name"|None,
    "comp"    : "component-name",
    "comp_id" : <int>
}

Retrieve all information of the signal name. Returns None if the name was not found. Otherwise, returns a dictionary with the signal information:

result = hal.query.signal("my.signal.name")
result = {
    "haltype" : "signal",
    "name"    : "my.signal.name",
    "type"    : hal.Type.<BOOL,REAL,SINT,UINT,PORT,S32,U32>,
    "value"   : <bool, int or float>,
    "writers" : <int>,
    "readers" : <int>,
    "bidirs"  : <int>,
    "driver"  : "driver.pin.name"|None
}

Retrieve all information of the component name or by integer component id. Returns None if the name or id was not found. Otherwise, returns a dictionary with the component information:

result = hal.query.comp("component-name")
result = {
    "haltype" : "component",
    "name"    : "component-name",
    "type"    : hal.CompType.<REALTIME,USER,OTHER>
    "id"      : <int>
    "pid"     : <int>|0
    "ready"   : True|False,
    "insmod"  : "comp command line options"
}

Retrieve all information of the function name. Returns None if the name was not found. Otherwise, returns a dictionary with the function information:

result = hal.query.funct("my.funct.name")
result = {
    "haltype"   : "function",
    "name"      : "my.funct.name",
    "comp"      : "component-name",
    "comp_id"   : <int>,
    "users"     : <int>,
    "reentrant" : True|False
}

Retrieve all information of the thread name. Returns None if the name was not found. Otherwise, returns a dictionary with the thread information:

result = hal.query.thread("my.thread.name")
result = {
    "haltype"   : "thread",
    "name"      : "my.thread.name",
    "comp"      : "component-name",
    "comp_id"   : <int>,
    "priority"  : <int>,
    "period"    : <int>, # in nanoseconds
    "functions" : (
        {
            "haltype" : "threadfunction",
            "name"    : "my.funct.name",
            "index"   : <int>,
            "is_init" : True|False
        },
        ...
    )
}

Retrieve information about all pins connected to signal name. Returns None if the signal name is not found. The dictionary returned may be empty and has the format:

result = hal.query.signalpins("my.signal")
result = {
    "pin-r" : { "haltype": "pin", "name": "pin-r", "dir": hal.Dir.IN  "signal": "my.signal", ...},
    "pin-w" : { "haltype": "pin", "name": "pin-w", "dir": hal.Dir.OUT "signal": "my.signal", ...},
    "pin-x" : { "haltype": "pin", ...},
    ...
}

Retrieve information about all pins. The dictionary returned has the format:

{
    "pin-a" : { "haltype": "pin", "name": "pin-a", "type":...},
    "pin-b" : { "haltype": "pin", ...},
    ...
}

Retrieve information about all params. The dictionary returned has the format:

{
    "param-a" : { "haltype": "parameter", "name": "param-a", "type":...},
    "param-b" : { "haltype": "parameter", ...},
    ...
}

Retrieve information about all signals. The dictionary returned has the format:

{
    "sig-a" : { "haltype": "signal", "name": "sig-a", "type":...},
    "sig-b" : { "haltype": "signal", ...},
    ...
}

Retrieve information about all components. The dictionary returned has the format:

{
    "comp-a" : { "haltype": "component", "name": "comp-a", "type":...},
    "comp-b" : { "haltype": "component", ...},
    ...
}

Retrieve information about all functions. The dictionary returned has the format:

{
    "funct-a" : { "haltype": "function", "name": "funct-a", ...},
    "funct-b" : { "haltype": "function", ...},
    ...
}

Retrieve information about all threads. The dictionary returned has the format:

{
    "thread-a" : { "haltype": "thread", "name": "thread-a", ...},
    "thread-b" : { "haltype": "thread", ...},
    ...
}

Allocate a size sized shared memory segment with ID key.

Returns a Python memoryview object of the shared memory segment.

This is non-functional. Do not use. You cannot increase or decrease the shared memory segment’s size once it is created.

A port is a special pin type. It is created as a normal pin with type hal.Type.PORT. You need two pins for a port, one input and one output. Both ends of a port are connected with a signal (net). Setting the signal will allocate the port’s queue.

Returns the number of bytes available for reading from the port queue.

Returns the number of bytes possible to write to the port queue.

Write a buffer onto the port queue. The argument data can be either a bytes buffer or a string. If it is a string, then it will be converted to a UTF-8 bytes buffer. Returns True if the data was successfully written to the port queue and False if not. The write() call fails if the port queue has not enough free capacity for the entire data argument.

Reads size bytes from the port and removes the bytes from the port queue. The port is tested whether size bytes are available before attempting to read. Returns a bytes buffer upon success or False on failure.

Reads size bytes from the port without removing the bytes from the port queue. The port is tested whether size bytes are available before attempting to peek. Returns a bytes buffer upon success or False on failure.

Removes size bytes from the port queue. Returns True on success or False if not.

Clears the content of the port queue.

Return the allocated port queue size. The return value is zero (0) if no queue was allocated for the port.