There are a lot of things one can do if they are able to interface their electronics to their desktop / laptop computer. It's easier than ever to make these connections, especially with Circuit Playground Express.

The USB specification has several ways to characterize devices. This includes telling the computer that the device you are plugging into the USB port is a keyboard or mouse. These peripherals are categorized as human interface devices (HID). 

Many Adafruit products can communicate with other computers using HID and emulating a mouse.

What types of projects work well emulating a mouse? Some examples:

• Assistive Technology - the ability to trigger keyboard input using a multitude of interface devices connected to the microcontroller
• Simulating mouse clicks with another device.
• Making a mouse jiggler to keep a computer from falling asleep

This guide will show you how to quickly and easily emulate a mouse on an Adafruit Circuit Playground Express board in both Microsoft MakeCode and CircuitPython.

Parts List

If you are new to Microsoft MakeCode, you can learn the basics of MakeCode here.

To add keyboard support, MakeCode needs to load an extension - to bring in some blocks that are not usually loaded in the main program. To do this, click on the ADVANCED blog group:

Then click on the EXTENSION block:

And select the mouse - Mouse emulation over HID extension:

This adds a new block group on the main MakeCode page called MOUSE with several new functional blocks when you click the group button:

At this point you will want to define some action that lets your program know you wish to use one of the mouse functions. This can be anything but for example you may want to trigger mouse input on:

• Press of the A or B buttons or the slide switch
• Press of a capacitive touch pad (marked A1 to A7)
• On a loud sound, shake of the board, or bright light
• Periodically move the mouse after several seconds, minutes, hours, etc.

For a simple demonstration, here are four button event blocks from the INPUT block group on button click - the A button on Circuit Playground Express clicks the left mouse button (down when A is down, up when A is up). If Button B is pressed, it simulates the right mouse button clicked down, up when B is released. 

Moving the Cursor

You can also define moving the cursor. Ideas include:

• Using the Circuit Playground Express accelerometer tilt
• Using buttons or capacitive touch on the outside pads

The following example uses the capacitive touch pads to move in the x and y direction.

Pads A3 and A4 move the mouse horizontally, pads A7 and A1 move the cursor vertically.

Here is the code in action:

If you are new to CircuitPython, we recommend you start with the Welcome to CircuitPython Guide then come back here.

Adafruit recommends installing and using the Mu editor, available for Windows, macOS, and Linux. You can learn about Mu in this guide.

The adafruit_hid Library

Adafruit has developed libraries to easily use CircuitPython devices which have HID capabilities as mouse devices. There are several functions you may wish to use in your programs, this guide will show them with examples.

The adafruit_circuitplayground Library

Adafruit has developed a library to access much of the functionality on the Circuit Playground Express called adafruit_circuitplayground. You can use the library by defining 
from adafruit_circuitplayground.express import cpx at the start of your code. The library has functions for all the sensors, buttons, etc. The examples will use cpx.button_a and cpx.button_b to read the pushbuttons.

Performing Mouse Clicks

The following performs a mouse left click when Circuit Playground Express Button A is pressed, a right click when Button B is pressed:

# SPDX-FileCopyrightText: 2018 Anne Barela for Adafruit Industries
#
# SPDX-License-Identifier: MIT

import usb_hid
from adafruit_circuitplayground.express import cpx
from adafruit_hid.mouse import Mouse

m = Mouse(usb_hid.devices)

while True:
    if cpx.button_a:
        m.press(Mouse.LEFT_BUTTON)
        while cpx.button_a:    # Wait for button A to be released
            pass
        m.release(Mouse.LEFT_BUTTON)

    if cpx.button_b:
        m.press(Mouse.RIGHT_BUTTON)
        while cpx.button_b:    # Wait for button B to be released
            pass
        m.release(Mouse.RIGHT_BUTTON)

# SPDX-FileCopyrightText: 2018 Anne Barela for Adafruit Industries
#
# SPDX-License-Identifier: MIT

import usb_hid
from adafruit_circuitplayground.express import cpx
from adafruit_hid.mouse import Mouse

m = Mouse(usb_hid.devices)

while True:
    if cpx.button_a:
        m.press(Mouse.LEFT_BUTTON)
        while cpx.button_a:    # Wait for button A to be released
            pass
        m.release(Mouse.LEFT_BUTTON)

    if cpx.button_b:
        m.press(Mouse.RIGHT_BUTTON)
        while cpx.button_b:    # Wait for button B to be released
            pass
        m.release(Mouse.RIGHT_BUTTON)

When a button is pressed, the code sends the mouse button press notification. It then waits, doing nothing while the button is still pressed. When the button is not pressed anymore, the code sends a mouse release button call.

Moving the Mouse Cursor

The following uses 4 of the capacitive touch pads on the Circuit Playground Express to signal having the mouse move in the +x, +y, -x, and -y axis. This can be changed to switch activations or other methods such as using the accelerometer chip to move based on tilt of the Circuit Playground circuit board.

# SPDX-FileCopyrightText: 2018 Anne Barela for Adafruit Industries
#
# SPDX-License-Identifier: MIT

import usb_hid
from adafruit_circuitplayground.express import cpx
from adafruit_hid.mouse import Mouse

m = Mouse(usb_hid.devices)
cpx.adjust_touch_threshold(200)

while True:
    if cpx.touch_A4:
        m.move(-1, 0, 0)
    if cpx.touch_A3:
        m.move(1, 0, 0)
    if cpx.touch_A7:
        m.move(0, -1, 0)
    if cpx.touch_A1:
        m.move(0, 1, 0)

# SPDX-FileCopyrightText: 2018 Anne Barela for Adafruit Industries
#
# SPDX-License-Identifier: MIT

import usb_hid
from adafruit_circuitplayground.express import cpx
from adafruit_hid.mouse import Mouse

m = Mouse(usb_hid.devices)
cpx.adjust_touch_threshold(200)

while True:
    if cpx.touch_A4:
        m.move(-1, 0, 0)
    if cpx.touch_A3:
        m.move(1, 0, 0)
    if cpx.touch_A7:
        m.move(0, -1, 0)
    if cpx.touch_A1:
        m.move(0, 1, 0)

Documentation

The online documentation for the Adafruit HID library is available at on readthedocs.

Adafruit has another guide that goes over the functionality of the adafruit_circuitplayground (CPX) library functions.

Going Further

The mouse keys and cursor code can be merged to one overall mouse program with buttons and cursor control. 

This type of work is terrific for assistive technologies projects.

You can also make a mouse jiggler program which uses the time library along with the mouse library to move the mouse a little, sleep, then do it again. This may keep a computer awake if it has auto shutdown which you cannot change.