covvi-eci 1.1.6

This project provides the ethernet interface to the COVVI Hand.

COVVI Ethernet Control Interface (ECI)

This software is used to communicate and control the COVVI Robotic Hand over ethernet.

You can:

• discover the ECI on the network.
• turn the power on/off to the hand.
• control the 5 digits plus the rotation of the thumb independently or all together.
• move the hand to pre-defined grip patterns.
• read realtime data such as digit positions, digit status, finger-tip pressure, orientation, environmental data.
• define custom callback functions for the realtime data.

---

Contents

• Getting Started
  • Installing Python
  • Checking Python
  • Installing the ECI package
    • Virtual Environment
      • Creating a Virtual Environment
      • Activating the Virtual Environment
      • Checking the Virtual Environment
    • Installing the Python ECI API Package
    • Checking the Python API Package installed correctly
• Python Preamble
• Discovering the COVVI Interface
  • Connecting/Disconnecting the interface
  • Quick Start Example
• Hand Power
• Discovery and device messages
  • Hello
  • Firmware
  • DeviceIdentity
  • DeviceProduct
• Real-time messages
  • RealtimeCfg
• DigitControl
  • DigitStatus
  • DigitPosn
  • CurrentGrip
  • DirectControl
  • DigitMove
  • MotorCurrent
  • DigitError
• Digit configuration messages
  • DigitConfig
  • PinchConfig
• Grip configuration messages
  • GripName
• System and status messages
  • Environmental
  • SystemStatus
  • Orientation
• Firmware update messages
  • SendUserGrip
  • RemoveUserGrip

---

Getting Started ^

If you are familiar with Python and you have the COVVI Hand connected via Ethernet (with a DHCP server) and power cable, you can skip to Discovery and device messages.

---

Installing Python

Ubuntu

  Python is installed by default for Ubuntu but if you want to install an alternate version, you can find those here: https://www.python.org/downloads/source/

Windows

  For windows, Python (>=3.8) installers can be downloaded from: https://www.python.org/downloads/windows/

  Allow Python through your firewall if windows asks for your permission.

---

Checking Python

  Run the folloing commands in a terminal/command prompt/powershell.

  Check that Python is installed: python3 -V or python -V. This should output something similar to "Python 3.12.8".

---

Installing the ECI package

  Installing the ECI Python package is a simple process.

Virtual Environment

  It is recommended to protect your installed packages (but not necessary) by using a virtual environment.

Creating a Virtual Environment

  Run this command to check that python virtual environments are installed:

   python3 -m pip install virtualenv

  Create a project folder and change the working directory of your terminial to the project folder.

  Then create a virtual environment:

   python3 -m venv .venv

---

Activating the Virtual Environment

  Then activate this virtual environment:

    Ubuntu: source ./.venv/bin/activate

    PowerShell: .\.venv\Scripts\Activate.ps1

    Command Prompt: .\.venv\Scripts\activate.bat

---

Checking the Virtual Environment

  On Ubuntu, you can check that your environment is activated with:

    type python pip

    This should output something similar to:

      python is /path/to/your/project/.venv/bin/python

      pip is /path/to/your/project/.venv/bin/pip

  In PowerShell/Command Prompt, you can check that your environment is activated with:

    where.exe python

    This should output some lines of text, with the first line being something similar to:

      C:\path\to\your\project\.venv\Scripts\python.exe

---

Installing the Python ECI API Package

  Install the ECI package via:

    pip install covvi-eci

---

Checking the Python API Package installed correctly

  Check that the package installed correctly:

  Ubuntu: pip list --format=freeze | grep 'covvi-eci'

  PowerShell/Command Prompt: pip list --format=freeze | findstr covvi-eci

  Both of these commands should show something similar to "covvi-eci==1.1.6"

---

Python Preamble ^

All coding examples from this point on assume that:

• the COVVI Hand is connected to power.
• your computer is connected to an IPv4 network (Ethernet or Wifi).
• the COVVI Hand is connected by ethernet to the same network (preferably with a DHCP server, i.e., your router).
• the red power light is blinking periodically (indicating that power is supplied to the COVVI Hand).
• the green and amber LEDs are lit (indicating that the COVVI Hand is connected to a ethernet network).
• Python v3.8 and above is installed and running on your computer.
• your virtual environment is created, activated, and the Python ECI API Package is installed.
• you have an IDE (Integrated Development Environment) that you are familiar with (i.e. VSCode or even a simple text editor).

You can enable logging debug mode if you wish to see debug messages.

import logging
logging.getLogger().setLevel(logging.DEBUG)

Return logging to warning mode if you wish to hide the debug messages.

import logging
logging.getLogger().setLevel(logging.WARNING)

---

Discovering the COVVI Interface ^

Below is an example code snippet for programmatically discovering the interface. In this example, the IP address of the network interface to discover on is: 192.168.1.1.

To find the IP address of your network adapters, run the following commands:

Terminal (Ubuntu): ifconfig.

Command Prompt/PowerShell (Windows): ipconfig.

Here is an example of obtaining the IP address of the hand by providing the serial number:

from eci import get_discovery_from_serial
msg = get_discovery_from_serial('192.168.1.1', serial_number=1234)
print(msg)
HOST = msg.ip
print(f'The HOST has been set to: {HOST}')

Or set the IP address manually:

HOST = '192.168.1.5'

Connecting/Disconnecting the interface

All interactions with the ECI occur through the context manager: CovviInterface. It opens and closes the interface:

from eci import CovviInterface
with CovviInterface(HOST) as eci:
    ...

If the 'with' clause is a problem in your application, then you can always use the start and stop functions to start and stop the COVVI Interface. Using start and stop is preferable when your application uses multiple threads and callback functions.

from eci import CovviInterface
eci = CovviInterface(HOST).start()
...
eci.stop()

Quick Start Example

Below is a quick example of the COVVI Hand opening, closing, and then opening. Change the serial_number to that of your COVVI Hand.

from time import sleep
from eci import CovviInterface, get_discovery_from_serial

msg = get_discovery_from_serial(serial_number=1002)
print(msg)
HOST = msg.ip
print(f'The HOST has been set to: {HOST}')

with CovviInterface(HOST) as eci:
    eci.setHandPowerOn()
    eci.setDirectControlOpen()
    sleep(2)
    eci.setDirectControlClose()
    sleep(2)
    eci.setDirectControlOpen()
    sleep(2)
    eci.setHandPowerOff()

The rest of this README is a comprehensive list of all the commands that can be send to the COVVI Hand.

---

Hand Power ^

setHandPowerOn() - Turn the power on to the hand

from eci import CovviInterface
with CovviInterface(HOST) as eci:
    print(eci.setHandPowerOn())

setHandPowerOff() - Turn the power off to the hand

from eci import CovviInterface
with CovviInterface(HOST) as eci:
    print(eci.setHandPowerOff())

Subsequent code snippets assume that setHandPowerOn() has already been called and that the power to the hand is on. Power to the hand can be determined manually via a blue LED on the 'CAN' label on the hand.

---

Discovery and device messages ^

Hello

getHello() - Get a simple 'hello' response from the ECI

from eci import CovviInterface
with CovviInterface(HOST) as eci:
    print(eci.getHello())

Firmware

getFirmware_PIC() - Get the PIC Firmware version

from eci import CovviInterface
with CovviInterface(HOST) as eci:
    print(eci.getFirmware_PIC_ECI())
    print(eci.getFirmware_PIC_HAND()) # Requires power to the hand (blue LED on)

DeviceIdentity

getDeviceIdentity() - Get device identity parameters

from eci import CovviInterface
with CovviInterface(HOST) as eci:
    print(eci.getDeviceIdentity())

DeviceProduct

getDeviceProduct() - Get product and manufacturer

from eci import CovviInterface
with CovviInterface(HOST) as eci:
    print(eci.getDeviceProduct())

---

Real-time messages ^

RealtimeCfg

setRealtimeCfg() - Set real-time update configuration

Turn all realtime packets on

from eci import CovviInterface
with CovviInterface(HOST) as eci:
    eci.enableAllRealtimeCfg()

from time import sleep
from eci import CovviInterface
with CovviInterface(HOST) as eci:
    for _ in range(4):
        eci.setRealtimeCfg(
            digit_status    = True,
            digit_posn      = True,
            current_grip    = True,
            electrode_value = True,
            input_status    = True,
            motor_current   = True,
            digit_touch     = True,
            digit_error     = True,
            environmental   = True,
            orientation     = True,
            motor_limits    = True,
        )
        sleep(2)
        eci.setRealtimeCfg(
            digit_status    = False,
            digit_posn      = False,
            current_grip    = False,
            electrode_value = False,
            input_status    = False,
            motor_current   = False,
            digit_touch     = False,
            digit_error     = False,
            environmental   = False,
            orientation     = False,
            motor_limits    = False,
        )
        sleep(2)

Turn all realtime packets off

from eci import CovviInterface
with CovviInterface(HOST) as eci:
    eci.disableAllRealtimeCfg()

from eci import CovviInterface
with CovviInterface(HOST) as eci:
    eci.setRealtimeCfg(
        digit_status    = False,
        digit_posn      = False,
        current_grip    = False,
        electrode_value = False,
        input_status    = False,
        motor_current   = False,
        digit_touch     = False,
        digit_error     = False,
        environmental   = False,
        orientation     = False,
        motor_limits    = False,
    )

from eci import CovviInterface
with CovviInterface(HOST) as eci:
    eci.setRealtimeCfg()

Setting the callbacks for each realtime message type

from eci import CovviInterface
with CovviInterface(HOST) as eci:
    eci.callbackDigitStatusAll  = print
    eci.callbackDigitPosnAll    = print
    eci.callbackCurrentGrip     = print
    eci.callbackElectrodeValue  = print
    eci.callbackInputStatus     = print
    eci.callbackMotorCurrentAll = print
    eci.callbackDigitTouchAll   = print
    eci.callbackDigitError      = print
    eci.callbackEnvironmental   = print
    eci.callbackOrientation     = print
    eci.callbackMotorLimits     = print

Turn all realtime packets on and print all the parameters of each packet

from eci import CovviInterface
with CovviInterface(HOST) as eci:
    eci.callbackDigitStatusAll  = print
    eci.callbackDigitPosnAll    = print
    eci.callbackCurrentGrip     = print
    eci.callbackElectrodeValue  = print
    eci.callbackInputStatus     = print
    eci.callbackMotorCurrentAll = print
    eci.callbackDigitTouchAll   = print
    eci.callbackDigitError      = print
    eci.callbackEnvironmental   = print
    eci.callbackOrientation     = print
    eci.callbackMotorLimits     = print

    eci.setRealtimeCfg(
        digit_status    = True,
        digit_posn      = True,
        current_grip    = True,
        electrode_value = True,
        input_status    = True,
        motor_current   = True,
        digit_touch     = True,
        digit_error     = True,
        environmental   = True,
        orientation     = True,
        motor_limits    = True,
    )
    from time import sleep
    sleep(60 * 10)

resetRealtimeCfg() - Reset the realtime callbacks (and stop streaming realtime messages)

from eci import CovviInterface
with CovviInterface(HOST) as eci:
    eci.resetRealtimeCfg()

---

Digit Control ^

DigitStatus

getDigitStatus_all() - Get all digit status flags

from eci import CovviInterface
with CovviInterface(HOST) as eci:
    print(eci.getDigitStatus_all())

getDigitStatus() - Get all digit status flags individually

from eci import CovviInterface, Digit
with CovviInterface(HOST) as eci:
    for digit in Digit:
        print(digit.name, eci.getDigitStatus(digit))

DigitPosn

getDigitPosn_all() - Get all digit positions

from eci import CovviInterface
with CovviInterface(HOST) as eci:
    print(eci.getDigitPosn_all())

getDigitPosn() - Get all digit positions individually

from eci import CovviInterface, Digit
with CovviInterface(HOST) as eci:
    for digit in Digit:
        print(digit.name, eci.getDigitPosn(digit))

setDigitPosn() - Set all digit positions individually - Close the hand fully

from eci import CovviInterface
with CovviInterface(HOST) as eci:
    eci.setDigitPosn(speed=50, thumb=0xFF, index=0xFF, middle=0xFF, ring=0xFF, little=0xFF, rotate=0xFF)

setDigitPosn() - Set all digit positions individually - Open the hand fully

from eci import CovviInterface
with CovviInterface(HOST) as eci:
    eci.setDigitPosn(speed=50, thumb=0, index=0, middle=0, ring=0, little=0, rotate=0)

setDigitPosn() - Set all digit positions individually - Perform a thumbs up

from time import sleep
from eci import CovviInterface
with CovviInterface(HOST) as eci:
    eci.setDigitPosn(speed=50, thumb=0, index=0, middle=0, ring=0, little=0, rotate=0)
    sleep(1)
    eci.setDigitPosn(speed=50, thumb=0, index=0xFF, middle=0xFF, ring=0xFF, little=0xFF, rotate=0)

CurrentGrip

getCurrentGrip() - Get the current grip

from eci import CovviInterface
with CovviInterface(HOST) as eci:
    print(eci.getCurrentGrip())

setCurrentGrip(grip_id) - Set the current grip

from eci import CovviInterface, CurrentGripID
with CovviInterface(HOST) as eci:
    print(eci.setCurrentGrip(grip_id=CurrentGripID.GN0))

setCurrentGrip(grip_id) - Set the current grip to <current_grip_id>

from eci import CovviInterface, CurrentGripID
with CovviInterface(HOST) as eci:
    print(eci.setCurrentGrip(grip_id=CurrentGripID.PREC_CLOSED))

from eci import CovviInterface, Percentage
with CovviInterface(HOST) as eci:
    eci.setDirectControlClose(speed=Percentage(value=100))

from eci import CovviInterface, Percentage
with CovviInterface(HOST) as eci:
    eci.setDirectControlOpen(speed=Percentage(value=100))

from eci import CovviInterface
with CovviInterface(HOST) as eci:
    eci.setDirectControlStop()

DirectControl

setDirectControlClose() - Close the whole hand

from eci import CovviInterface
with CovviInterface(HOST) as eci:
    eci.setDirectControlClose(speed=100)

setDirectControlOpen() - Open the whole hand

from eci import CovviInterface
with CovviInterface(HOST) as eci:
    eci.setDirectControlOpen(speed=100)

DigitMove

setDigitMove() - Command to move each digit individually - Open the whole hand

from eci import CovviInterface, Digit
with CovviInterface(HOST) as eci:
    for digit in Digit:
        eci.setDigitMove(digit, position=40, speed=50, power=20, limit=0)

setDigitMove() - Command to move each digit individually - Close the whole hand

from eci import CovviInterface, Digit
with CovviInterface(HOST) as eci:
    for digit in Digit:
        eci.setDigitMove(digit, position=210, speed=50, power=20, limit=0)

setDigitMove() - Open the index digit

from eci import CovviInterface, Digit
with CovviInterface(HOST) as eci:
    eci.setDigitMove(Digit.INDEX, position=44, speed=50, power=20, limit=0)

setDigitMove() - Close the index digit

from eci import CovviInterface, Digit
with CovviInterface(HOST) as eci:
    eci.setDigitMove(Digit.INDEX, position=210, speed=50, power=20, limit=0)

setDigitMove() - Command to move each digit individually - Set the digits to random positions

from random import randint
from eci import CovviInterface, Digit
with CovviInterface(HOST) as eci:
    for digit in Digit:
        eci.setDigitMove(digit, position=randint(40, 200), speed=50, power=20, limit=0)

MotorCurrent

getMotorCurrent_all() - Get the motor current of all Digits

from eci import CovviInterface
with CovviInterface(HOST) as eci:
    print(eci.getMotorCurrent_all())

getMotorCurrent() - Get the motor current of all Digits individually

from eci import CovviInterface, Digit5
with CovviInterface(HOST) as eci:
    for digit in Digit5:
        print(digit.name, eci.getMotorCurrent(digit))

DigitError

getDigitError() - Get the digit error flags of all digits individually

from eci import CovviInterface, Digit
with CovviInterface(HOST) as eci:
    for digit in Digit:
        print(digit.name, eci.getDigitError(digit))

---

Digit configuration messages ^

DigitConfig

getDigitConfig() - Get the limits of each digit individually

from eci import CovviInterface, Digit
with CovviInterface(HOST) as eci:
    for digit in Digit:
        print(digit.name, eci.getDigitConfig(digit))

PinchConfig

getPinchConfig() - Get the pinch points of each digit individually

from eci import CovviInterface
with CovviInterface(HOST) as eci:
    print(eci.getPinchConfig())

---

Grip configuration messages ^

GripName

getGripName

from eci import CovviInterface, GripNameIndex
with CovviInterface(HOST) as eci:
    for grip_name_i in list(GripNameIndex):
        print(grip_name_i, eci.getGripName(grip_name_i))

---

System and status messages ^

Environmental

getEnvironmental() - Get the temperature, humidity, battery voltage values of the hand

from eci import CovviInterface
with CovviInterface(HOST) as eci:
    print(eci.getEnvironmental())

SystemStatus

getSystemStatus() - Get the system status

from eci import CovviInterface
with CovviInterface(HOST) as eci:
    print(eci.getSystemStatus())

Orientation

getOrientation() - Get the orientation of the hand

from eci import CovviInterface
with CovviInterface(HOST) as eci:
    print(eci.getOrientation())

---

Firmware update messages ^

SendUserGrip

sendUserGrip(grip_index, grip_path) - Send a User Grip

from eci import CovviInterface, GripNameIndex, UserGripID
with CovviInterface(HOST) as eci:
    print(eci.sendUserGrip(GripNameIndex.GN0, UserGripID.THUMBS_UP))
    for grip_name_i in list(GripNameIndex):
        print(grip_name_i, eci.getGripName(grip_name_i))

resetUserGrips() - Reset all the User Grips

from eci import CovviInterface, GripNameIndex
with CovviInterface(HOST) as eci:
    eci.resetUserGrips()
    for grip_name_i in list(GripNameIndex):
        print(grip_name_i, eci.getGripName(grip_name_i))

RemoveUserGrip

removeUserGrip(grip_index) - Remove a User Grip

from eci import CovviInterface, GripNameIndex
with CovviInterface(HOST) as eci:
    print(eci.removeUserGrip(GripNameIndex.GN0))
    for grip_name_i in list(GripNameIndex):
        print(grip_name_i, eci.getGripName(grip_name_i))