search

debrouxl / hplp

Windows / MacOS X / Linux third-party connectivity kit library / linking software for the newest HP calculators, targeting the Prime at first. It is strongly derived from libti*, https://github.com/debrouxl/tilibs , which implements communication with all TI graphing calculator families.
42 stars 8 forks source link

readme

hplp: code for communicating with recent HP calculators

hplp (still entirely in libhpcalcs for now) is the beginning of a toolkit for two-way communications with HP Prime calculators.

See below for detailed build instructions. Note that the install_hplp.sh script provided alongside this README ( https://raw.github.com/debrouxl/hplp/master/install_hplp.sh ) automates part of the build process.

Status (2014/06/03)

The code base does:

The code base doesn't:

Goals

Laying the groundwork for GUIs dealing with two-way communication with HP Prime calculators, and possibly 39gII (Prime and 39gII are similar), using USB HID class, and possibly later fake MSD for firmware upgrades.

Non-goals

As far as I'm concerned, working by myself on:

Build process summary

As mentioned above, the repository contains an script for automating the part of the build strictly related to libhpcalcs / hplp: install_hplp.sh .

The build process is that of pretty much any autotools-based piece of software: $ autoreconf -i -f $ ./configure $ ./make check

make install

The terminal-based test program is in tests/test_hpcalcs.

For now, the main external dependency of libhpcalcs is HIDAPI: https://github.com/signal11/hidapi.git Unless your Linux distro packages it (few do), you need to compile and install it yourself (it is also an autotools-based project: configure, make, make install).

Detailed build & configuration process for Debian, Ubuntu, Mint and derivatives (courtesy of Jonathan Cameron)

  1. Install build dependencies (packages required for building libhpcalcs). As root (with root shell, or sudo)

    (sudo) apt-get install build-essential git autoconf automake autopoint libtool gettext xdg-utils libpng-dev libudev-dev libusb-1.0-0-dev autotools-dev

  2. Install hidapi:

$ mkdir -p $HOME/lpg # or anywhere else you see fit $ cd $HOME/lpg $ git clone https://github.com/signal11/hidapi.git hidapi $ cd hidapi

Follow the directions from the README.txt file:

$ ./bootstrap $ ./configure --prefix=/usr $ make

As root (with root shell, or sudo):

(sudo) make install <----- as root, or using sudo

  1. Install libhpcalcs

Download https://raw.github.com/debrouxl/hplp/master/install_hplp.sh and copy it to, for instance, $HOME/hplp

$ cd $HOME/lpg $ chmod +x install_hplp.sh

(sudo) ./install_hplp.sh

  1. Test hplp

As root, verify that you can run test_hpcalcs. Plug in your HP Prime to the computer and turn it on. Wait about 10 seconds and then run:

$ $HOME/lpg/hplp/libhpcalcs/tests/test_hpcalcs

You should see the menu of possible operations. If you do, hplp is working and you are successfully communicating with your Prime.

  1. Set up for normal users to access the Prime with the test software.

    a. If you are on your own isolated computer (e.g, laptop), then add the following udev rules to the new file /etc/udev/rules.d/82-hp-prime.rules :

    # HP Prime Calculator
SUBSYSTEM=="usb",  ATTRS{idVendor}=="03f0", ATTRS{idProduct}=="0441", MODE="0666"
KERNEL=="hidraw*", ATTRS{idVendor}=="03f0", ATTRS{idProduct}=="0441", MODE="0666"

    Note that anyone on your system will be able to access your Prime with the hplp software.

    If you are on a shared system and you want to avoid anyone accessing the device but you, do this instead:

    # HP Prime Calculator
SUBSYSTEM=="usb",  ATTRS{idVendor}=="03f0", ATTRS{idProduct}=="0441", ACTION=="add", GROUP="dialout", MODE="0664"
KERNEL=="hidraw*", ATTRS{idVendor}=="03f0", ATTRS{idProduct}=="0441", ACTION=="add", GROUP="dialout", MODE="0664"

and add yourself to the 'dialout' group.  You may need to switch to
the new group for this to work (eg: newgrp dialout).

    To activate the new udev rule, turn off your HP Prime, turn it back on, and wait for about 10 seconds. Then, check the permissions for the device (in /dev/hidraw? and /dev/usb/hiddev?).

NOTES:

Technical notes

The code leverages HIDAPI, and it was strongly inspired by the time-proven concepts and APIs of the libti family, which I (Lionel Debroux) am the current maintainer of. The GPL'ed libti family ( https://github.com/debrouxl/tilibs ) forms the back-end for TILP, TIEmu, TilEm and titools (mainly), and contains the only third-party portable FLOSS code with two-way communication support for all three series of TI-Z80, TI-68k and TI-Nspire graphing calculators. Putting together framework strongly inspired by libti* clearly took some work, but having such a foundation saves time in the longer term. IOW, it's worth the apparent complexity.

Obviously, until the calculator's protocol is better documented, the API will change in backwards-incompatible manners (for instance, the output parameters of check ready and get infos operations).

TODO list

License

Copyright (C) 2013-2015 Lionel Debroux

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.

Changelog

2013/11/03 - 2013/12/30: improve logging, create install_hplp.sh, improve error passing, fix bugs reported by more beta-testers, add more operations. 2013/10/22 - 2013/11/03: Created autotools-based project and test client; vastly expand the code, to the point it becomes releasable (if not really usable). First public announcement (limited scope). 2013/10/21: Split into multiple files, but still piggybacking hidtest.cpp. 2013/10/20: First public PoC. 2013/10/19: Project started.

Credits (demoscene style)