API Reference

grove_vision_ai_v2

Circuitpython Support for using the Grove Vision AI V2 with pre-built models.

Communication with the Grove Vision AI V2 board is over a UART connection.

Written for AT API “v0”, softrware version “2025.01.02”

  • Author(s): Ned Konz

Implementation Notes

Hardware:

Software and Dependencies:

References

class grove_vision_ai_v2.ATDevice(uart_tx, uart_rx, uart_bufsize: int = 1024, bufsize: int = 1024)

Bases: object

Main interface to the Grove Vision AI V2 board via UART AT commands.

This class handles communication with the Grove Vision AI V2 board using the AT command protocol over UART at 921600 baud. It provides methods for running inference, capturing images, and querying device information.

uart

UART bus object for communication.

Type:

busio.UART

Example

>>> import board
>>> from grove_vision_ai_v2 import ATDevice, CMD_OK
>>> ai = ATDevice(board.TX, board.RX)
>>> if ai.invoke(1, True, True) == CMD_OK:
...     print(f"Detected {len(ai.boxes)} objects")

Initialize communication with the Grove Vision AI V2 board.

Parameters:

  • uart_tx – TX pin for UART communication.

  • uart_rx – RX pin for UART communication.

  • uart_bufsize – Size of UART receiver buffer in bytes. Default 1024. Increase if bytes are being lost.

  • bufsize – Size of response buffer in bytes for JSON parsing. Default 1024. Increase if responses are being truncated.

Note

Even with adequate buffer sizes, using invoke() or sample_image() to capture images runs the risk of data loss, and you may end up with broken JPEG images. This is especially likely with an active USB connection.

at_api() → str | None

Get the AT API version string.

Returns:

AT API version string (e.g., “v0”), or None on error.

property boxes: list[Box]

List of Box objects from last detection inference.

property classes: list[Class]

List of Class objects from last classification inference.

clean_actions() → int

Clear all configured actions.

Returns:

CMD_OK (0) on success, or error code.

property debug: bool

Enable debug output for commands and responses.

static get_error_name(code: int) → str

Get the string name for a given error code.

Parameters:

code – The integer error code.

Returns:

The string representation of the error code (e.g., “OK”, “ETIMEDOUT”).

id(cache: bool = True) → str | None

Get the device ID.

Parameters:

cache – If True, return cached value if available. Default True.

Returns:

Device ID string, or None on error.

property image: Image | None

Image object from last SAMPLE command or INVOKE command (if requested).

info(cache: bool = True) → str | None

Get the model information as a base64-encoded string.

Use model_info() to get the decoded model metadata.

Parameters:

cache – If True, return cached value if available. Default True.

Returns:

Base64-encoded model info string, or None on error.

invoke(times: int, diffonly: bool, resultonly: bool, timeout: float = 0.1) → int

Run inference on the loaded model.

Results are stored in instance attributes (boxes, classes, points, keypoints, perf).

Parameters:

  • times – Number of times to run inference (usually 1).

  • diffonly – If True, only return results that differ from previous inference.

  • resultonly – If True, only return inference results without image data.

  • timeout – Maximum time to wait for results in seconds. Default 0.1.

Returns:

CMD_OK (0) on success, or error code (CMD_ETIMEDOUT, etc.).

Example

>>> if ai.invoke(1, True, True) == CMD_OK:
...     for box in ai.boxes:
...         print(f"Detected object at ({box.x}, {box.y})")
property keypoints: list[Keypoint]

List of Keypoint objects from last keypoint inference.

model_info() → dict | None

For a model loaded from the Sensecraft web site, return a dict describing the model.

Example:

{
    "author": "SenseCraft AI",
    "model_id": "60086",
    "model_name": "Person Detection--Swift YOLO",
    "model_ai_framwork": "6",
    "checksum": "f2b99229ba108c82de9379c4b6ad6354",
    "arguments": {
        "createdAt": 1705306231,
        "size": 1644.08,
        "task": "detect",
        "conf": 50,
        "iou": 45,
        "updatedAt": 1747633412,
        "icon": "https://sensecraft-statics.oss-accelerate.aliyuncs.com/refer/pic/1705306138275_iykYXV_detection_person.png",
        "url": "https://sensecraft-statics.oss-accelerate.aliyuncs.com/refer/model/1705306215159_jVQf4u_swift_yolo_nano_person_192_int8_vela(2).tflite",
    },
    "classes": ["person"],
    "version": "1.0.0",
}
name(cache: bool = True) → str | None

Get the device name.

Parameters:

cache – If True, return cached value if available. Default True.

Returns:

Device name string, or None on error.

property perf: Perf

Performance metrics from last inference (Perf object).

perform_command(cmd: str, tag: str | None = None) → int

Perform a raw AT command.

The response will be available in self.response.

Parameters:

  • cmd – Command string (e.g., “MODEL=1”, “MODELS?”).

  • tag – Optional tag for the command. Default None.

Returns:

CMD_OK (0) on success, CMD_ETIMEDOUT on timeout, or other error code.

Example

>>> ai.perform_command("MODEL=1")  # Switch to model 1
>>> print(ai.response)
property points: list[Point]

List of Point objects from last point inference.

property response: dict | None

Last JSON response received from the device.

property response_bufsize: int

Size of the response buffer in bytes. Setting this to a new value re-allocates the buffer and does a GC collection.

sample_image(times: int = 1, timeout: float = 0.1) → int

Capture an image from the camera without running inference.

The image data is stored in the image attribute as an Image object.

Parameters:

  • times – Number of images to capture (usually 1).

  • timeout – Maximum time to wait for image capture in seconds. Default 0.1.

Returns:

CMD_OK (0) on success, or error code (CMD_ETIMEDOUT, etc.).

Example

>>> if ai.sample_image() == CMD_OK and ai.image:
...     with open('capture.jpg', 'wb') as f:
...         f.write(ai.image.data)
save_jpeg() → int

Configure the board to save captured images to SD card.

Requires an SD card to be mounted on the AI board. Use clean_actions() to disable this feature.

Returns:

CMD_OK (0) on success, or error code.

version(cache: bool = True) → dict | None

Get the firmware version information.

Parameters:

cache – If True, return cached value if available. Default True.

Returns:

Dictionary with version info including ‘at_api’, ‘software’, etc., or None on error.

class grove_vision_ai_v2.Box(x: int, y: int, w: int, h: int, score: int, target: int)

Bases: object

Bounding box detection result from object detection models.

The box is represented with center coordinates (x, y) and dimensions (w, h).

x

X-coordinate of box center in pixels (0-240 for default camera resolution).

y

Y-coordinate of box center in pixels (0-240 for default camera resolution).

w

Width of box in pixels.

h

Height of box in pixels.

score

Confidence score (0-100).

target

Target class index.

property bottom: float

Bottom edge y-coordinate of the box.

property left: float

Left edge x-coordinate of the box.

property right: float

Right edge x-coordinate of the box.

property top: float

Top edge y-coordinate of the box.

class grove_vision_ai_v2.Class(score: int, target: int)

Bases: object

Classification result from image classification models.

score

Confidence score (0-100).

target

Target class index.

exception grove_vision_ai_v2.DecodeError

Bases: ValueError

class grove_vision_ai_v2.Image(base64: str)

Bases: object

JPEG image data decoded from base64.

data

Raw JPEG image bytes.

Initialize Image from base64-encoded string.

Parameters:

base64 – Base64-encoded JPEG image data from the AI board.

class grove_vision_ai_v2.Keypoint(box: Box, points: list[Point])

Bases: object

Keypoint detection result combining a bounding box with multiple points.

Used for pose estimation and similar tasks where objects have multiple landmarks.

box

Bounding box containing the detected object.

points

List of Point objects representing keypoints/landmarks.

class grove_vision_ai_v2.Perf(preprocess: int = 0, inference: int = 0, postprocess: int = 0)

Bases: object

Performance metrics from model inference.

preprocess

Preprocessing time in milliseconds.

inference

Inference time in milliseconds.

postprocess

Postprocessing time in milliseconds.

class grove_vision_ai_v2.Point(x: int, y: int, score: int, target: int)

Bases: object

Point detection result, used for landmarks or keypoint detection.

x

X-coordinate in pixels.

y

Y-coordinate in pixels.

score

Confidence score (0-100).

target

Target point index.