Controls LCD of SpaceExplorer Enterprise

Andrew Black 1a13cb7f06 Fix incorrect name; Add button event test 6 months ago
.hooks a83c90637a General tidy; Add spacenavd patch 6 months ago
bin a83c90637a General tidy; Add spacenavd patch 6 months ago
doc a83c90637a General tidy; Add spacenavd patch 6 months ago
res 1a13cb7f06 Fix incorrect name; Add button event test 6 months ago
src 1a13cb7f06 Fix incorrect name; Add button event test 6 months ago
sub 2cc8a262cd SVG / Python working / Add Inkscape exporter 6 months ago
.clang-format b0d74b22f1 Initial commit 7 months ago
.ctags_extra_dirs 2cc8a262cd SVG / Python working / Add Inkscape exporter 6 months ago
.gitignore a83c90637a General tidy; Add spacenavd patch 6 months ago
.gitmodules 2cc8a262cd SVG / Python working / Add Inkscape exporter 6 months ago
Makefile a83c90637a General tidy; Add spacenavd patch 6 months ago
README.md 1a13cb7f06 Fix incorrect name; Add button event test 6 months ago

README.md

SpaceLCD

SpaceLCD logo

SpaceLCD displays SVG images on the SpaceMouse Enterprise 3D mouse. It can also contol the LCD brightness.

Getting Started

Prerequisites

SpaceLCD requires libusb to control the 3D mouse, librsvg to parse the SVG and also zlib to compress the images.

Optional requirements are swig for generating the Python bindings, and Unity for running the unit tests.

Note: During development, Bear and ctags are in use in places in the Makefile. You can choose to either install the packages or comment out those areas.

Installing

Clone the repository and build the library and Python module:

git clone --recursive https://github.com/TheHoodedFoot/spacelcd.git
cd spacelcd/src
make

Permissions

Spacelcd needs write permissions for the SpaceMouse. There are some example udev rules included.

Code Example

import spacelcd

with open ("logo.svg", "r") as svgfile:
    svg=svgfile.readlines()

spacelcd.svgtolcd(svg[0], spacelcd.scroll.left)

Photo showing SpaceLCD logo

Background

The SpaceMouse Enterprise has a 640x150 pixel display with 16-bit R5G6B5 colour support. Images are sent to the display with a 512-byte header, followed by the bitmap, which is compressed using raw deflate.

SpaceLCD is only used to control the display; spacenavd and libspnav are required in order to read the motion data from the mouse.

Limitations

The official 3DConnexion driver has some support for animation, which is not currently understood and therefore not implemented here. The proprietary driver can also use partial screen updates, whereas SpaceLCD uploads the full screen each time.

SpaceLCD has only been tested using one SpaceMouse Enterprise, with USB ID 256f:c633, bought as part of the SpaceMouse Enterprise Kit 3DX-700058.

The header uses a 16-bit value to hold the length of the compressed bitmap, limiting its size to 65535 bytes.

Operating system support is currently GNU/Linux only.

Using the SpaceMouse Enterprise with as a 3d mouse with spacenavd

The current version of spacenavd, 0.6, does not include the USB vendor and product ids for the SpaceMouse Enterprise, so although SpaceLCD can control the display, the device itself will not work as a 3d mouse. A patch for spacenavd is included here which adds the SpaceMouse Enterprise as a recognised device. The patch also blacklists the CadMouse, which is a regular mouse that comes as part of the SpaceMouse Enterprise kit, which spacenavd mistakenly recognises as a 3d mouse.

Bugs

Device Lockup

The SpaceMouse is vulnerable to corrupted data, which can cause the display to become unresponsive, requiring a hard reset. SpaceLCD will also generate corrupt data under certain circumstances, which is being investigated.

Endianness Issues

Because this code has only been developed on an x86 system, the endianness of 16-bit words has probably been taken for granted in several places, so it may work incorrectly on another architecture.

Inkscape Plugin

The code also includes a plugin for Inkscape version 1.0, which requires scour to be installed. The plugin uploads the current Inkscape drawing to the SpaceMouse, which is useful when prototyping GUI elements.

Built With

  • libusb - Portable, userspace USB access
  • zlib - Compression algorithm used by the SpaceMouse
  • librsvg - Used to generate a bitmap from SVG data

Authors

  • Andrew Black - Initial work - github

License

This project is licensed under the zlib License

Acknowledgments

  • spacenavd / libspnav
  • zlib