Locator

The locator module allows to detect connected NXT bricks and to create corresponding Brick objects.

The find() function is your main starting point to create a NXT-Python program.

If you want to make a command line tool, add_arguments() and find_with_options() will make it easy to allow choosing a brick from the command line.

nxt.locator.find(*, find_all=False, backends=None, custom_match=None, config='default', config_filenames=None, name=None, host=None, **filters)

Find a NXT brick and return it.

Parameters:

  • find_all (bool) – True to return an iterator over all bricks found.

  • backends (Iterable[str or object] or None) – Specify backends to use, use None for default.

  • custom_match (Callable or None) – Function to filter bricks found.

  • config (str or None) – Name of the configuration file section to use, or None to disable configuration reading.

  • config_filenames (Iterable[str or bytes or os.PathLike] or None) – Configuration file paths, or None for default.

  • name (str or None) – Brick name (example: "NXT").

  • host (str or None) – Bluetooth address (example: "00:16:53:01:02:03").

  • filters – Additional filter keywords or backends parameters.

Returns:

The found brick, or an iterator if find_all is True

Return type:

nxt.brick.Brick or Iterator[nxt.brick.Brick]

Raises:

BrickNotFoundError – if no brick is found and find_all is False.

Use this function to find a NXT brick. You can pass arguments to match a specific brick, for example, this will return the brick with name “NXT”:

>>> import nxt.locator
>>> b = nxt.locator.find(name="NXT")

If there is more than one matching brick, the first one found will be returned. If no brick is found, BrickNotFoundError is raised.

If you want to find all matching bricks, you can set the find_all parameter to True. It will return an iterator on all found bricks. If no brick is found, an empty iterator is returned.

You can also use a custom function to search for your brick:

>>> def is_my_brick(brick):
...     name = brick.get_device_info()[0]
...     return name.startswith("NXT")
...
>>> for b in nxt.locator.find(find_all=True, custom_match=is_my_brick):
...     b.play_tone(440, 1000)
...

The name and host parameters are passed to the backends, and are also used to filter the result, so you can use the host parameter even when not using Bluetooth.

Extra keywords arguments are given to the backends which can use them or not. See the nxt.backend documentation.

The backends parameter allows overriding the default list of backends to use. Each element of the list is a backend object or a backend name. Again, see nxt.backend documentation for the list of available backends.

Configuration is used to load default values for backends parameter and selection parameters. If the config parameter is not None, a configuration will be read from files listed by the config_filenames parameter, or from a default list of files. The config parameter corresponds to the section to use for configuration.

nxt.locator.add_arguments(parser)

Add options to an argparse parser to allow configuration from the command line.

Parameters:

parser (argparse.ArgumentParser) – An argparse parser.

This can be used to easily design a command line interface. Use it with find_with_options().

Example:

>>> import argparse
>>> import nxt.locator
>>> p = argparse.ArgumentParser(description="My NXT-Python program")
>>> nxt.locator.add_arguments(p)
>>> p.add_argument("--hello", help="say hello (example)")
>>> options = p.parse_args()
>>> brick = nxt.locator.find_with_options(options)
nxt.locator.find_with_options(options, *, find_all=False)

Find a NXT brick and return it, using options from command line.

Parameters:
Returns:

The found brick or None, or an iterator if find_all is True.

Return type:

nxt.brick.Brick or None or Iterator[nxt.brick.Brick]

This is to be used together with add_arguments(). It calls find() with options received on the command line.

exception nxt.locator.BrickNotFoundError

Exception raised when searching for a NXT brick, but no brick can be found.