Guide d'intégration du SDK PMSOpticDll V4.4.7 pour objectifs zoom motorisés

Le SDK PMSOptical expose 44 fonctions C exportées depuis une seule DLL Windows, couvrant la connexion série et Ethernet, le contrôle de position absolue, la lecture en retour de l'état, les fonctions de la carte de commande chiffrée et une famille d'API complète et parallèle pour les objectifs double moteur. Le flux de travail central est de quatre appels : ouverture → retour à l'origine → déplacement → attente. Un handle est obtenu avec PMSOptical_OpenComm("COM1", 9600) pour le série, ou PMSOptical_OpenSocket("192.168.1.200", 4196) pour le TCP.

Ce guide documente les familles de fonctions, la séquence d'appels recommandée, et les quatre contraintes d'intégration qui causent la plupart des problèmes d'intégration au premier essai — y compris l'une qui compte pour la sécurité des machines : le SDK ne contient aucun arrêt d'urgence logiciel utilisable.

L'essentiel en un coup d'œil

Élément	Valeur
Fonctions exportées	44 (24 mono-moteur, 20 double moteur)
Plateforme	Windows x64 / x86 (DLL)
Connexion	Série à 9600 bauds, ou TCP sur le port 4196
Type de handle	PMSHANDLE (void*) — toujours vérifier qu'il n'est pas nul
Séquence centrale	Open → GoHome → MoveTo(pulse) → WaitForOpticalFinished → GetPos → Close
Délai d'attente par défaut de l'API d'attente	100000 ms (100 s)
Fonctions non implémentées	8, dont Stop et Stop2
Liaisons de langage	C++ natif ; C# via P/Invoke ; autres langages via ctypes/cffi (aucune liaison officielle)

Structure du package

PMSOptical-SDK/
├── Doc/
│   ├── POMEAS electric lens development documents V4.4.7.pdf   (English)
│   ├── encrypted / non-encrypted development documents V4.4.7  (control-card comparison)
│   └── dual-motor control card operation manual V1.5
├── SDK/
│   ├── include/PMSOpticalDll.h            44 exported functions
│   ├── x64/{Release,Debug}/PMSOpticalDll.dll + .lib
│   │   └── OP/*.txt                       per-model pulse tables
│   └── x86/{Release,Debug}/               same, 32-bit
└── demo/
    └── x64/PMSOpticalDemo.exe + .ini      MFC demo application

La DLL doit se trouver à côté de l'exécutable ou sur le PATH système.

Connexion

Méthode	Fonction	Paramètres
Série	PMSOptical_OpenComm(char* comname, int nBaud)	comname tel que "COM1" ; nBaud = 9600
Ethernet	PMSOptical_OpenSocket(char* ip, int nPort)	ip tel que "192.168.1.200" ; nPort = 4196
Interrogation d'état	PMSOptical_IsOpened(PMSHANDLE, bool&)	—
Fermeture	PMSOptical_Close(PMSHANDLE&)	Handle passé par référence

Pour une connexion réseau, le PC hôte et la carte de commande de l'objectif doivent être sur le même sous-réseau — les trois premiers octets doivent correspondre, par exemple 192.168.1.xxx. Le masque de sous-réseau est obtenu automatiquement.

#include "PMSOpticalDll.h"

PMSHANDLE h = PMSOptical_OpenComm("COM2", 9600);            // serial
// PMSHANDLE h = PMSOptical_OpenSocket("192.168.1.200", 4196);  // Ethernet
if (!h) { /* connection failed */ }

Les 44 fonctions, par famille

Famille 1 — gestion de la connexion (1–4)

N°	Fonction	But
1	PMSOptical_OpenSocket(char* ip, int nPort)	Ouvrir via Ethernet, renvoyer le handle de l'appareil
2	PMSOptical_OpenComm(char* comname, int nBaud)	Ouvrir via série, renvoyer le handle de l'appareil
3	PMSOptical_IsOpened(PMSHANDLE, bool& bIsOpened)	Indiquer si le handle est ouvert
4	PMSOptical_Close(PMSHANDLE&)	Fermer le handle

Les fonctions 3 et 4 passent leur résultat et leur handle par référence. C'est délibéré : l'en-tête note que les signatures ont été façonnées ainsi pour la compatibilité C# P/Invoke.

Famille 2 — contrôle mono-moteur (5–15)

N°	Fonction	But	Implémentée
5	GoHome(PMSHANDLE)	Retour à l'origine	Oui
6	IsHomed(PMSHANDLE, bool&)	Indiquer si le retour à l'origine est terminé	Non — marqué unrealized
7	MoveTo(PMSHANDLE, int nPulse)	Déplacement vers une position absolue en impulsions	Oui
8	Stop(PMSHANDLE)	Arrêt immédiat	Non — marqué unrealized
9	JogStart(PMSHANDLE, int nJogSpeed)	Jog (vitesse positive ou négative)	Non — marqué unrealized
10	JogStop(PMSHANDLE)	Arrêter le jog	Non — marqué unrealized
11	GetPos(PMSHANDLE, int& nCurPulse)	Lire la position courante	Oui
12	GetMaxPos(PMSHANDLE, int& nMaxPulse)	Lire l'impulsion maximale (course totale)	Oui
13	GetStatus(PMSHANDLE, int& nStatus)	Lire l'état du mouvement : 0 en mouvement, 1 arrêté, 2 échec d'initialisation	Oui
14	WaitForOpticalFinished(PMSHANDLE, int nTimeOut = 100000)	Bloquer jusqu'à la fin du mouvement de zoom	Oui
15	GetVer(PMSHANDLE, char* Ver)	Lire la version du firmware	Oui

WaitForOpticalFinished encapsule la logique de polling d'état en interne — interrogeant l'état et vérifiant l'indicateur d'arrêt — avec un délai d'attente par défaut de 100000 ms. Dans la plupart des applications, vous devez l'appeler plutôt qu'écrire votre propre boucle de polling.

Famille 3 — carte de commande chiffrée (16–24)

Disponible uniquement lorsque l'objectif est équipé de la carte de commande chiffrée (indiquée par encrypt dans le nom de fichier de la table d'impulsions).

N°	Fonction	But
16	EncryptCommStatus(PMSHANDLE, bool& IsConnected)	Indique si la carte chiffrée est connectée
17	EncryptReadTimes(PMSHANDLE, int& nTimes)	Lire le compteur de cycles de zoom
18	EncryptWriteTimes(PMSHANDLE, int nTimes)	Écrire le compteur de cycles de zoom
19	EncryptAddTimes(PMSHANDLE)	Incrémenter le compteur de cycles de zoom
20	EncryptReadFlashMaxPos(PMSHANDLE, int&)	Lire l'impulsion maximale stockée dans la Flash
21	EncryptWriteFlashMaxPos(PMSHANDLE, int)	Écrire l'impulsion maximale dans la Flash
22	EncryptCheckHomeStatus(PMSHANDLE, bool& bHasStatus, bool& bNowStatus)	État du retour à l'origine et du fin de course
23	EncryptReadFlashLensInfo(PMSHANDLE, unsigned char buf[64])	Lire les informations d'objectif (bloc fixe de 64 octets)
24	EncryptWriteFlashLensInfo(PMSHANDLE, unsigned char buf[64])	Écrire les informations d'objectif (ASCII imprimable uniquement)

À quoi sert réellement la carte chiffrée : elle stocke le compteur de cycles de zoom et un bloc d'identité d'objectif de 64 octets dans la Flash de la carte de commande. Cela prend en charge le suivi des actifs matériels, les statistiques d'utilisation et l'identification des objectifs authentiques — directement utile pour les intégrateurs de machines, les flottes de location et la maintenance après-vente.

Famille 4 — objectifs double moteur (25–44)

Chaque fonction ci-dessus a une version parallèle avec un suffixe 2 et un paramètre final unsigned char u8lensnum = 0 qui sélectionne le moteur 1 ou 2.

Mono-moteur	Double moteur	But
GoHome	GoHome2(h, u8lensnum)	Retour à l'origine du moteur sélectionné
IsHomed	IsHomed2(h, bool&, u8lensnum)	Non réalisé
MoveTo	MoveTo2(h, nPulse, u8lensnum)	Déplacer le moteur sélectionné vers une position absolue
Stop	Stop2(h, u8lensnum)	Non réalisé
JogStart / JogStop	JogStart2 / JogStop2	Non réalisé
GetPos	GetPos2(h, int&, u8lensnum)	Lire la position
GetMaxPos	GetMaxPos2(h, int&, u8lensnum)	Lire la course totale
GetStatus	GetStatus2(h, int&, u8lensnum)	Lire l'état
WaitForOpticalFinished	WaitForOpticalFinished2(h, nTimeOut, u8lensnum)	Attendre la fin
GetVer	GetVer2(h, char*, u8lensnum)	Lire la version du firmware
Encrypt* (9 fonctions)	Encrypt*2(h, …, u8lensnum)	Ensemble complet de la carte chiffrée

Les objectifs double moteur associent un moteur de zoom à un moteur de trim de mise au point indépendant — par exemple un objectif zoom 12.5X avec un trim de mise au point motorisé 12 mm, ou un 12.5X double moteur avec un axe de trim 3 mm.

// Dual motor: motor 0 = zoom, motor 1 = focus trim
PMSOptical_GoHome2(h, 0);
PMSOptical_MoveTo2(h, 4600, 0);                        // zoom to 1X (see the model pulse table)
PMSOptical_WaitForOpticalFinished2(h, 100000, 0);

Séquence d'appels recommandée

Open (serial or Ethernet)
   |
GoHome()  ->  WaitForOpticalFinished(timeout)
   |
GetMaxPos()  ->  validate total travel, and confirm the link is alive
   |
+-- MoveTo(pulse)
|     ->  WaitForOpticalFinished(timeout)   (or poll GetStatus until it returns 1)
|     ->  GetPos()  ->  compare with target (closed loop)
+-- repeat for the next magnification
   |
Close()

L'organigramme de référence du fabricant spécifie trois règles pour le chemin de polling :

1. Attendre au moins 50 ms avant chaque requête d'état.
2. Définir un délai d'attente global — le manuel suggère 10 secondes ou plus.
3. Si le délai d'attente global expire sans réponse valide, déclarer une erreur de connexion de l'objectif et quitter proprement.

Quatre contraintes d'intégration

1. Les communications s'arrêtent pendant que le moteur bouge

Pendant que la carte de commande entraîne le moteur, les communications sont suspendues. Une requête d'état peut ne renvoyer aucune donnée. Traitez cela par expiration de délai et nouvelle tentative, ou en appelant WaitForOpticalFinished. Ne le traitez pas comme une panne et ne redémarrez pas la connexion.

2. Une requête de déplacement égale à la position courante ne fait rien

Si l'impulsion demandée est égale à l'impulsion courante, l'objectif ne bouge pas et signale le succès. N'utilisez jamais « commande envoyée » comme test de vivacité de la liaison. Utilisez plutôt GetMaxPos ou GetPos.

3. L'initialisation à la mise sous tension prend 25–35 secondes

À la mise sous tension, l'objectif revient à l'origine, et il n'accepte aucune commande pendant cette fenêtre. Une application hôte doit attendre au moins 35 secondes avant d'ouvrir la connexion et d'émettre des commandes. Ne pas en tenir compte est une cause fréquente de rapports « appareil ne répond pas » qui ne sont pas de vraies pannes.

4. Il n'y a pas d'arrêt d'urgence logiciel

Stop et Stop2 sont tous deux marqués unrealized dans l'en-tête, ainsi que IsHomed, JogStart, JogStop et leurs équivalents double moteur — huit fonctions au total. Ne concevez pas de fonction de sécurité autour d'eux. Déterminez la fin avec GetStatus ou WaitForOpticalFinished, et implémentez l'arrêt d'urgence avec un circuit matériel — une coupure de courant ou un signal d'interverrouillage externe.

Règles matérielles dont dépend le logiciel

1. Connectez et verrouillez le câble moteur et le câble RS-232 avant d'appliquer la tension. Les connecter sous tension peut endommager le circuit de commande.
2. Ne connectez ou débranchez jamais le câble moteur sous tension. C'est l'action la plus destructrice sur le terrain et elle peut endommager le moteur de façon permanente.
3. Si le câble moteur doit dépasser 5 m, commandez le câble long d'usine. Ne soudez pas plusieurs câbles courts ni n'en fabriquez vous-même.
4. Choisissez série ou Ethernet, jamais les deux. La carte de commande prend l'un ou l'autre ; le mode de connexion logiciel doit correspondre au câblage matériel.

Carte de commande chiffrée ou standard ?

Besoin	Recommandation
Contrôle de zoom uniquement	Carte standard
Comptage d'utilisation, vérifications d'authenticité, facturation de location	Carte chiffrée (EncryptReadTimes, EncryptReadFlashLensInfo)
Flotte mixte	Notez que les deux cartes utilisent des tables d'impulsions différentes — changer de carte implique de changer la table

Questions fréquentes

Le SDK prend-il en charge Linux ou macOS ?

Le SDK officiel ne fournit que des DLL Windows (x64 et x86). Sur les autres plateformes, implémentez directement le protocole série — ce sont cinq commandes ASCII pures sans dépendance de plateforme, donc il fonctionne sur tout hôte disposant d'un port série ou d'une socket TCP.

Puis-je appeler le SDK depuis Python ?

Oui, via ctypes ou cffi, car les exports sont en liaison C. Il n'y a pas de liaison Python officielle, vous écrivez donc vous-même l'enveloppe. Notez que PMSHANDLE est un void* et que les paramètres bool& doivent être passés avec ctypes.byref.

Puis-je mélanger le SDK et les commandes série brutes ?

Techniquement oui, mais ne le faites pas sur la même liaison. Les deux adressent les mêmes registres matériels, et les mélanger — particulièrement autour de la référence de retour à l'origine — produit un état incohérent. Choisissez une approche par projet.

Quel délai d'attente utiliser pour WaitForOpticalFinished ?

La valeur par défaut est 100000 ms. Définissez-la à au moins deux fois le temps que prend le plus grand déplacement de zoom sur votre matériel. La valeur de référence du manuel est de 10 secondes ou plus.

Est-ce une interface de vision par IA ?

Non, et elle ne doit pas être décrite comme telle. Le SDK fournit une interface de contrôle d'optique programmable — position, état et lecture en retour. Il peut être intégré dans une architecture de vision par IA, où un logiciel de supervision émet une nouvelle commande de grossissement basée sur un résultat d'inspection, mais le SDK lui-même ne contient aucune capacité d'IA ou d'analyse d'image. La formulation exacte est que l'optique zoom motorisée peut être intégrée dans un flux de travail de vision industrielle contrôlé par IA.

Y a-t-il des problèmes connus dans le fichier d'en-tête ?

Deux valent la peine d'être connus. GetVer2 déclare son paramètre comme u8lennum — une faute de frappe qui n'affecte pas l'appel, mais qu'il vaut mieux normaliser dans votre propre enveloppe. Et les huit fonctions unrealized décrites ci-dessus ne doivent pas être utilisées.

À lire également

• Référence des commandes série RS-232 — la couche protocole sous le SDK
• Mappage grossissement vers position en impulsions — les valeurs passées à MoveTo
• Guide de dépannage de l'objectif zoom motorisé
• Optique programmable en vision industrielle

Produits associés

• Objectif zoom 12.5X motorisé pour inspection automatisée
• Objectif zoom coaxial 12.5X motorisé pour vision industrielle
• PMS-LZ-650104 — objectif zoom continu motorisé 6.5X
• Objectif zoom C-mount double moteur 12.5X