API Reference

adafruit_usb_host_mouse

Helper class that encapsulates the objects needed for user code to interact with a USB mouse, draw a visible cursor, and determine when buttons are pressed.

  • Author(s): Tim Cocks

Implementation Notes

Hardware:

Software and Dependencies:

# * Adafruit’s Bus Device library: https://github.com/adafruit/Adafruit_CircuitPython_BusDevice # * Adafruit’s Register library: https://github.com/adafruit/Adafruit_CircuitPython_Register

class adafruit_usb_host_mouse.BootMouse(device, interface_index, endpoint_address, was_attached, *, tilegrid=None, scale=1)

Helper class that encapsulates the objects needed to interact with a boot mouse, show a visible cursor on the display, and determine when buttons were pressed.

Parameters:

  • device – The usb device instance for the mouse

  • interface_index – The USB interface index of the mouse

  • endpoint_address – The address of the mouse endpoint

  • was_attached – A list of the usb devices detached from the kernel

  • tilegrid – The TileGrid that holds the visible mouse cursor

  • scale – The scale of the group that the Mouse TileGrid will be put into Needed in order to properly clamp the mouse to the display bounds

pressed_btns

List of buttons currently pressed (one or more of “left”, “right”, “middle”) If there’s no new mouse data (nothing changes) this property can be checked to see which buttons are currently pressed.

release()

Release the mouse cursor and re-attach it to the kernel if it was attached previously.

scale

The scale of the group that the Mouse TileGrid will be put into. Needed in order to properly clamp the mouse to the display bounds.

sensitivity

The sensitivity of the mouse cursor. Larger values will make the mouse cursor move slower relative to physical mouse movement. Default is 1.

tilegrid

TileGrid containing the Mouse cursor graphic.

update()

Read data from the USB mouse and update the location of the visible cursor and check if any buttons are pressed.

Returns:

a tuple containing one or more of the strings “left”, “right”, “middle” indicating which buttons are pressed. If no buttons are pressed, the tuple will be empty. If a error occurred while trying to read from the usb device, None will be returned.

property x: int

The x coordinate of the mouse cursor

property y: int

The y coordinate of the mouse cursor

class adafruit_usb_host_mouse.ReportMouse(device, interface_index, endpoint_address, was_attached, *, tilegrid=None, scale=1)

Helper class that encapsulates the objects needed to interact with a non-Boot mouse (Report), show a visible cursor on the display, and determine when buttons were pressed. The class is a subclass of BootMouse that overrides the update method.

Parameters:

  • device – The usb device instance for the mouse

  • interface_index – The USB interface index of the mouse

  • endpoint_address – The address of the mouse endpoint

  • was_attached – A list of the usb devices detached from the kernel

  • tilegrid – The TileGrid that holds the visible mouse cursor

  • scale – The scale of the group that the Mouse TileGrid will be put into Needed in order to properly clamp the mouse to the display bounds

update()

Read data from the USB mouse and update the location of the visible cursor and check if any buttons are pressed.

Returns:

a tuple containing one or more of the strings “left”, “right”, “middle” indicating which buttons are pressed. If no buttons are pressed, the tuple will be empty. If a error occurred while trying to read from the usb device, None will be returned.

adafruit_usb_host_mouse.find_and_init_boot_mouse(cursor_image=DEFAULT_CURSOR, scale=1)

Scan for an attached boot mouse connected via USB host. If one is found initialize an instance of BootMouse class and return it.

Parameters:

  • cursor_image – Provide the absolute path to the desired cursor bitmap image. If set as None, the BootMouse instance will not control a displayio.TileGrid object

  • scale – The scale of the group that the Mouse TileGrid will be put into Needed in order to properly clamp the mouse to the display bounds

Returns:

The BootMouse instance or None if no mouse was found.

adafruit_usb_host_mouse.find_and_init_mouse(cursor_image=DEFAULT_CURSOR, subclass=SUBCLASS_BOOT)

Scan for an attached mouse connected via USB host. If one is found return a tuple containing the parameters needed to initalize an instance of :class: BootMouse or :class: ReportMouse depending on the value of the subclass parameter.

Parameters:

  • cursor_image – Provide the absolute path to the desired cursor bitmap image. If set as None, the object instance created using the returned tuple will not control a displayio.TileGrid object.

  • subclass – Defines whether to search for boot or non-boot mice. SUBCLASS_BOOT (0X01), a boot mouse will be searched for SUBCLASS_RESERVED (0x00), a non-boot (report) mouse will be searched for

Returns:

A tuple containing the arguments needed by the calling find and init helper function. If no mouse is found None is returned.

adafruit_usb_host_mouse.find_and_init_report_mouse(cursor_image=DEFAULT_CURSOR, scale=1)

Scan for an attached report mouse connected via USB host. If one is found initialize an instance of ReportMouse class and return it.

Parameters:

  • cursor_image – Provide the absolute path to the desired cursor bitmap image. If set as None, the ReportMouse will not control a displayio.TileGrid object.

  • scale – The scale of the group that the Mouse TileGrid will be put into Needed in order to properly clamp the mouse to the display bounds

Returns:

The ReportMouse instance or None if no mouse was found.