# 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: Literal[False] = False, backends: Iterable[str | object] | None = None, custom_match: Callable[[Brick], bool] | None = None, config: str | None = 'default', config_filenames: Iterable[str | bytes | PathLike] | None = None, name: str | None = None, host: str | None = None, **filters: str | int | None) → Brick
nxt.locator.find(*, find_all: Literal[True], backends: Iterable[str | object] | None = None, custom_match: Callable[[Brick], bool] | None = None, config: str | None = 'default', config_filenames: Iterable[str | bytes | PathLike] | None = None, name: str | None = None, host: str | None = None, **filters: str | int | None) → Iterator[Brick]

  Find a NXT brick and return it.

  Parameters:

    - find_all – `True` to return an iterator over all bricks found.

    - backends – Specify backends to use, use `None` for default.

    - custom_match – Function to filter bricks found.

    - config – Name of the configuration file section to use, or `None` to disable configuration reading.

    - config_filenames – Configuration file paths, or `None` for default.

    - name – Brick name (example: `"NXT"`).

    - host – 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`

  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 (ArgumentParser) – An `argparse` parser.

  Return type:

    None

  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: Namespace, *, find_all: Literal[False] = False) → Brick
nxt.locator.find_with_options(options: Namespace, *, find_all: Literal[True]) → Iterator[Brick]

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

  Parameters:

    - options (argparse.Namespace) – Options returned by `argparse.ArgumentParser.parse_args()`

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

  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.