Utiliser une DLL dans un programme Java

Parfois en robotique et encore plus souvent en électronique, les fabricants imposent d’utiliser une DLL (ou Dynamic Linked Library) pour contrôler leur produit. Par exemple un modem radio (Ant) ou une carte d’interface entrée/sortie pour expérimentations (kits Velleman).

Il s’agit d’un groupe de fonctions réunis dans un fichier binaire (pas de code source disponible) que notre programme doit exécuter. Les DLL sont spécifiques à Windows (il existe aussi des bibliothèques logicielles de principe similaire sous Linux et MaxOS, les .so ou "shared objects", .dylib ou "dynamic library", .sl ou "shared library", etc...) et généralement on développe un programme en Basic ou en C/C++ pour les utiliser.

Dans cet article, nous allons expliquer comment appeler les fonctions d’une DLL, donc accéder aux ressources de notre équipement électronique, depuis un programme Java, en l’occurence depuis l’environnement "Processing" qui est vraiment très simple et très pratique (nous avons réalisé ou utilisé plusieurs applets Processing décrites sur ce site : étude du PID, oscilloscope minimal de Sofian Audry, radar, contrôleur 3D, ...).

La carte électronique que nous utiliserons est une K8055 "VM110" de Velleman, il s’agit d’une "USB Experiment Interface Board" qui est décrite dans un autre article de ce site.

Voici le code source du sketch d’exemple :

Principe d’accès à une DLL depuis Java

Une DLL est considérée comme une ressource "native", car il s’agit d’un binaire appelant des ressources bas-niveau du système d’exploitation, en l’occurence il s’agit ici d’exploiter les ressources HID créées par la liaison USB entre notre ordinateur PC et la carte d’expérimentation Velleman.

Java sait parler depuis longtemps à des ressources natives, via ce qu’on appelle une "Java Native Interface" ou JNI. Il existe de nombreuses utilisations de JNI, généralement pour appeler des programmes en C/C++ recompilés pour JNI puis intégrés au programme Java. Il ne s’agit pas toujours d’accéder à des ressources systèmes, mais parfois d’exporter des algorithmes complexes pour les exécuter plus rapidement ou pour communiquer avec une application non Java qu’il serait trop long, impossible ou inutile de migrer sous Java.

Dans notre cas (DLL fournie par un constructeur), il est impossible de recompiler le code pour indiquer qu’on souhaite utiliser JNI. Il faut trouver une solution d’interface Java / natif qui laisse la DLL inchangée. Un article sur le site web de Processing décrit un hack de Processing basé sur JNative, une extension open-source qui permet ce type d’accès dynamique aux fonctions d’une DLL.

Résumé des opérations à faire pour programmer l’accès

– étudier la DLL cible pour connaître ses fonctions
– installer la DLL dans le répertoire c :/Windows/system32
– créer une classe Java basée sur JNative
– écrire les opérations qui implémentent les accès à chaque fonction de la DLL
– écrire de nouvelles fonctions simplifiées indépendantes de JNative
– compiler le programme Java

Résumé de la chaîne d’exécution

– L’application Processing utilise des opérations simplifiées qui correspondent aux fonctionnalités proposées par la DLL.
– Ces opérations traitent l’encapsulation (configuration, gestion des exceptions, changement des types de données, call-back) en utilisant l’API JNative.
– Les classes de JNative prennent la main pour appeler une DLL JNative en passant les paramètres et récupérant les valeurs en retour.
– La DLL JNative traite chacun des appels Java en gérant l’accès à la DLL cible (directement de natif à natif) permettant ainsi de dépasser la limite de JNI qui nécessiterait une recompilation de la DLL cible.

Cas pratique

On va utiliser Processing et JNative pour écrire un programme d’accès à la carte d’expérimentation permettant de faire des lectures et écritures sur les ports numériques et analogiques via la liaison USB.

Etude de la DLL

Deux DLL sont fournies sur le cédérom d’installation et d’exemples fourni avec le kit K8055 : "K8055D.DLL" et "K8055D_C.DLL". La première est destinée aux programmes Visual Basic et Borland, tandis que la seconde est destinée aux programmes Visual C++, sans autre explication... difficile surtout pour ceux qui ne veulent utiliser aucun de ces logiciels.

Il faut tout d’abord vérifier les fonctions mises à dispostion dans chacune de ces DLL fournies par Velleman : cette étape pourrait être superflue car des spécifications (document PDF en français) sont fournies, mais c’est l’occasion surtout de noter le nom exact de ces fonctions tel que le compilateur utilisé par Velleman a pu les modifier. En effet, le compilateur "décore" ("mangle" en anglais) le nom des fonctions, en ajoutant des caractères devant et derrière. On va utiliser un petit utilitaire "dllexp" (disponible sur le site de Nirsoft) pour vérifier cela.

Voici ce que ça donne pour la DLL "K8055D" :

Et voici ce que ça donne pour la DLL "K8055D_C" :

La première version est plus sympathique, non ? On va commencer avec elle, et éviter de se coltiner des décorations parasites (même si elles ont certainement une utilité qui n’est pas le sujet du présent article... enfin j’espère qu’on aura pas à chercher leur utilité pour faire fonctionner JNative).

Installation de la DLL

Il faut copier K8055D.dll dans un répertoire du système d’exploitation connu de tous les programmes. Sans faire trop d’essais, j’ai choisi "c :/windows/system32" comme indiqué dans l’article d’origine (hack Processing en anglais).

Installation de Processing

C’est une application simple qui ne pose aucun problème. Consultez le site web : www.processing.org.

Installation de JNative

Il faut récupérer la dernière version de JNative : http://jnative.free.fr. On découvre au passage que c’est un projet (au moins en partie) français. Les livrables sont disponibles sous Sourceforge. On télécharge le jar et on le copie sous /libraries/JNative/library. On peut également extraire (à l’intérieur du jar dans la version que j’ai récupérée) le fichier JNative.DLL et le placer à côté du fichier JNative.jar.

Ecriture de la classe "wrapper" des fonctions de la DLL

Dans un nouveau "sketch" Processing (manipulez un peu l’interface pour vous familiariser avec ses concepts et voir quelques exemples d’applets), créez un fichier avec une extension .java et portant le nom (en respectant la casse, majuscule/minuscule) de votre DLL, ici "K8055D.java". Ce n’est pas habituel car Processing utilise son propre format ".pde" car il simplifie (pas de notion de "classe" dans les sketchs ordinaires). Dans notre cas, on gardera un sketch classique et le fichier .java est une classe secondaire donc on ne perd pas la simplicité de Processing.

Ce fichier "K8055D.java" une fois ajouté à l’interface d’édition de code de Processing, on va écrire son contenu en commençant par l’enveloppe, la "classe" à la sauce Processing :

import processing.core.*;

public class K8055D extends PApplet
{


}

Comme cette classe implémente l’encapsulation d’appels à la DLL par JNative, il faut ajouter toutes les références aux packages de JNative, et s’identifier comme faisant partie du package JNative :

package org.xvolks.jnative.util;

import processing.core.*;

...

Pour importer les références, Processing propose un menu pour chacune des "libraries" stockées dans son répertoire d’installation.

Tout le gros pavé d’import doit être copié en-dessous de la ligne "package" :

package org.xvolks.jnative.util;

import processing.core.*;

import org.xvolks.test.bug.*;
import org.xvolks.jnative.util.ole.*;
import org.xvolks.jnative.util.windows.hooks.*;
[... et une vingtaine de lignes comme ça ...]

public class K8055D extends PApplet
{


}

Maintenant que c’est fait, on va remplir la classe. D’abord en stockant en constante le nom exact de la DLL qui devra être indiqué à chaque fois dans les appels aux fonctions JNative.

public class K8055D extends PApplet
{

  public static final String DLL_NAME = "K8055D.DLL";

}

Puis on va s’intéresser aux appels JNative en eux-même. Le principe est d’avoir une variable pour stocker chaque "pont" entre Java et une fonction de la DLL. Cette variable sera initialisée la première fois que vous ferez appel à une fonction, puis restera prête à recevoir vos invocations suivantes :

  // Native-side function names
  private static JNative nNomDeLaFonction;
  
  // JNative implementation of DLL functions
  public static void NomDeLaFonction() throws NativeException, IllegalAccessException 
  {
    if(nNomDeLaFonction == null) 
    {
      nNomDeLaFonction = new JNative(DLL_NAME, "NomDeLaFonction");  // The actual "decorated" name in the DLL
    }
    nNomDeLaFonction.invoke();  // Finally, execute the native function 
  }

Et c’est tout (dans le cas où il n’y a aucun paramètre en entrée ni en sortie). Il suffit de faire ça pour chacune des fonctions, en remplaçant "NomDeLaFonction" par chacune des fonctions. Devant un film, ça passe vite :)

Notez bien qu’on a créé une instance d’objet JNative en passant le nom de la DLL et le "NomDeLaFonction" de la fonction. Si on utilise la DLL avec décorations, cela donne par exemple :

      nNomDeLaFonction = new JNative(DLL_NAME, "_NomDeLaFonction@4");  // The actual "decorated" name in the DLL

La gestion des paramètres

Prenons un exemple concret : ouvrir la connexion avec la carte. Il s’agit de la fonction OpenDevice qui prend en argument l’adresse de la carte selon la configuration des cavaliers SK5 et SK6 et qui retourne 1 si c’est réussi et 0 si ça ne fonctionne pas.

On va ajouter une ligne dans l’initialisation de l’instance JNative pour indiquer le type de la donnée de retour. Pas besoin de spécifier le type d’argument, il suffit d’ajouter sa valeur lors de l’invocation. Enfin la troisième ligne supplémentaire consiste à récupérer la valeur de retour selon le type concerné pour la retourner à notre tour.

  /**
   *
   */
  public static int OpenDevice(int address) throws NativeException, IllegalAccessException 
  {
    if(nOpenDevice == null) 
    {
      nOpenDevice = new JNative(DLL_NAME, "OpenDevice");  // The actual "decorated" name in the DLL
      nOpenDevice.setRetVal(Type.INT);      
    }
    nOpenDevice.setParameter(0, address);
    nOpenDevice.invoke();  // Finally, execute the native function 
    return nOpenDevice.getRetValAsInt(); // get native call's return value
  }

Il suffit maintenant de compléter chacune des opérations Java en fonction des paramètres et valeurs de retour indiquées dans la documentation des fonctions de la DLL et le tour est joué.

Simplification des appels depuis le sketch Processing

Comme on le voit dans les exemples de code ci-dessus, les opérations ne gèrent pas les exceptions de JNative et les renvoient pour traitement ultérieur. Si on appelait ces fonctions depuis le sketch Processing, il faudrait tout un tas de code "try... catch..." et plein d’imports des classes de la bibliothèque JNative... pas très "Processing" tout ça.

On va donc simplifier grandement en écrivant des fonctions intermédiaires. En plus, on va choisir des noms d’opérations et des types de données indépendant de ce que nous impose la carte K8055. J’ai choisi d’implémenter les opérations d’accès aux ports d’entrées/sorties numériques et analogiques "à la sauce Arduino" :
– digitalRead(pin)
– digitalWrite(pin, value)

  /**
   * Write a high or low value to a digital pin (or channel as K8055 refers to)
   * @arg pin : channel from 1 to 5
   * @arg value : true or false for HIGH or LOW
   */
  public static void digitalWrite(int pin, boolean value)
  {
    try {
      if (value) {
        SetDigitalChannel(pin);      
      } 
      else {
        ClearDigitalChannel(pin); 
      } 
    } 
    catch (NativeException ne)  {    
      println("Error ! "+ne.toString());   
    }
    catch (IllegalAccessException e)  {    
      println("Error ! "+e.toString());   
    }
  }

  /**
   * Reads the value from a specified digital pin (or channel as K8055 refers to)
   * @arg pin : channel from 1 to 5
   * @return boolean value (true for HIGH and false for LOW)
   */
  public static boolean digitalRead(int pin)
  {
    try {
      return (ReadDigitalChannel(pin) == 1);
    } 
    catch (NativeException ne)  {    
      println("Error ! "+ne.toString());   
    }
    catch (IllegalAccessException e)  {    
      println("Error ! "+e.toString());   
    }
    return false;
  }

Et c’est fini. Dans le code du sketch, à part l’import de la classe que vous venez d’écrire, rien de plus. Voici ce que ça donne pour faire clignoter une led toutes les secondes pendant une demi-seconde :

import org.xvolks.jnative.util.K8055D;

void setup() 
{
  K8055D.initCard(0);
}

void draw()
{ 
  K8055D.digitalWrite(1,true); 
  delay(500); 
  K8055D.digitalWrite(1,false);
  delay(500);  
}

Simple, n’est-il pas ? Voici les sources pour que vous puissiez continuer à implémenter toutes les fonctions de la DLL (je me suis peut être arrêté en route...) et faire tout ce que vous voulez avec !