POC sensor module development guide

Introduction — overview of development

Developing with POC sensor modules comes down to three main steps: install the library, initialize the API, and get the target function to read and write. That’s all. No device driver installation or wrestling with register specifications required.

Modules and “functions”

There is one important design concept: a single module can have multiple “functions”. For example, a combined temperature / humidity / pressure sensor provides three functions in one unit: temperature, humidity, and pressure. In an operation panel module with a buzzer, the button input, buzzer, and LED are each independent functions.

What your program operates on is not the module itself but this “function” unit. To read temperature, you get the temperature function; to drive a relay, you get the relay function. Because you can write code without caring which module the function is on, the structure keeps your code largely unaffected even if you change models later.

Choosing a connection mode

Simply specifying a single connection target when initializing the API determines the operating mode. This is the most effective aspect of this product series’ design.

Apart from this one line, no code changes are needed. A program developed over a direct USB connection can be moved as is to a networked production environment. This design is why the cost of moving from prototype to mass production is low.

Your first program

Read a temperature sensor value and drive a relay when it exceeds a threshold: using this configuration common in industrial applications as an example, we show the minimum code. It is written in Python, but the structure is exactly the same in other languages.

# Load the libraries
from yoctopuce.yocto_api import *
from yoctopuce.yocto_temperature import *
from yoctopuce.yocto_relay import *

# Initialize the API (direct USB mode)
errmsg = YRefParam()
if YAPI.RegisterHub("usb", errmsg) != YAPI.SUCCESS:
    sys.exit("Initialization failed: " + errmsg.value)

# Get the functions to use
t = YTemperature.FirstTemperature()
r = YRelay.FirstRelay()
if t is None or r is None:
    sys.exit("Module not found")

# Control loop
while True:
    value = t.get_currentValue()
    if value > 25: r.set_state(YRelay.STATE_B)
    if value < 24: r.set_state(YRelay.STATE_A)
    YAPI.Sleep(100, errmsg)

Two design points

Add hysteresis to the threshold. In the example above, the relay switches on at 25℃ and back at 24℃. If the same value is used for both decisions, the relay will chatter violently when the measured value fluctuates around the threshold. Because this directly affects the lifespan of mechanical relays, a dead band of about 1℃ is standard practice.

Use the API Sleep for waiting. The language’s standard sleep stops the entire process, but the API Sleep keeps internal communication with the module going while waiting. Use it so that device attach/detach detection and event handling work correctly.

Supported languages and setup

All major development environments are covered, so you can choose one that fits your existing in-house systems.

Two setup methods

• Via a package manager — Python (pip), Node.js (npm), Java (Maven), Android (Gradle), and others can be installed with a single command. Because versions can be pinned, this method is recommended for team development and CI environments.
• Direct placement of source and binaries — Extract the distribution archive and add it to your path. Use this method in environments where you do not want to depend on a package manager, or in offline environments.

Watch out for missing native libraries

When distributing executables built with C#, Java, LabVIEW, and similar, the native library for USB access (.dll / .so / .dylib) is required. IDE auto-packaging features may not include it, which is a typical cause of a “library not found” error on the target machine even though everything works on the development machine. Also note that the 64bit version must be placed in the designated subdirectory.

Designing with logical names

There are three ways to get a function. Use the one that fits your use case.

Why logical names are recommended

You can write an arbitrary logical name to each module. The setting is stored in non-volatile memory, so once set, you can refer to the module by that name from then on. This has two practical advantages.

• Readability — Even in a system made up of many modules, code reads with names like furnace temperature / exhaust fan. Compared with a list of serial numbers, this makes a big difference to maintainability.
• Easy replication — When building multiple units of the same equipment, there is no need to rewrite code to match the serial number of each unit. The same program can be distributed as is.

Moving to a network configuration

A system built with direct USB connections can be extended as-is to a configuration over the network. The only change is a single initialization argument.

# During development: direct connection to the PC
YAPI.RegisterHub("usb", errmsg)

# Production: control devices behind a hub on the network
YAPI.RegisterHub("192.168.1.2", errmsg)

# When authentication is configured
YAPI.RegisterHub("admin:password@192.168.1.2", errmsg)

This alone lets you place sensors on site and the collecting side somewhere else. When handling multiple sites, call initialization for each site and you can handle them all simultaneously from one program.

Hub products for network connection

Depending on the application, choose wired LAN (with PoE power support), wireless LAN, or LTE / cellular. A major practical advantage is that you can swap only the communication method while keeping the sensor-side program the same.

Callback method (NAT traversal)

On mobile networks and typical corporate LANs, you cannot connect directly to a hub from outside, because it has no global IP and sits behind NAT. The callback method .

The direction of communication is the reverse of normal. Because the hub periodically connects to the server, it works as long as outbound traffic is allowed. No router or firewall configuration changes are required, which greatly lowers the barrier to adoption.

Two methods

• HTTP callback — The module connects to a script on the server at fixed intervals. The advantage is that it works in environments that cannot run resident processes, such as PHP. However, each exchange is a single, self-contained connection, so continuous two-way interaction is not possible.
• WebSocket callback — Maintains two-way communication. Because the server can query the module, you can go beyond data collection to remote control. Suited to environments that can run a resident server, such as Node.js or Java.

Handling multiple modules

Read values regardless of type

All sensor function classes, such as temperature, illuminance, and voltage, inherit from a common base class. Using this base class, you can write generic code that works with any sensor type. Because the current value and unit are retrieved with common methods, you do not need to add code every time you add a model.

# Code limited to temperature sensors
sensor = YTemperature.FirstTemperature()

# Code that works with any sensor type
sensor = YSensor.FirstSensor()
# → Works with any connected sensor: temperature, illuminance, voltage, air pressure, etc.

Notes for GUI applications

Unlike a console app, a GUI cannot keep reading values in an infinite loop. Instead, use a timer to call the processing periodically, and include the following.

• Calling event handling — Hand control to the API periodically.
• Re-fetching the device list — This is required to detect new connections, but it is a heavy operation, so limit it to intervals of about 2 seconds. Calling it every time makes the UI sluggish.
• Online check — Users unplug cables at unexpected times. Always check the status before access, and prepare a display for when the device is disconnected.

In full-scale applications, we also recommend moving API calls to a separate thread. Network-based configurations in particular involve communication waits, so handling them on the UI thread degrades responsiveness.

Common pitfalls

“Already in use by another process” error

This is the most common inquiry. It is caused by the restriction that only one process on the same PC can use direct USB mode. It occurs when you run your own program while the configuration tool is still running.

The solution is to keep a virtual hub running and have the program connect by specifying 127.0.0.1. This allows multiple programs to access the module simultaneously. During development you will often use the configuration tool and your program together, so setting up this configuration from the start makes things easier.

Distributed executable doesn’t run

Most cases are the missing native libraries mentioned above. The development machine has everything set up, so the problem is easy to miss and is first discovered on the deployment target. We recommend explicitly specifying the library output location in your packaging settings and testing once in a clean environment.

Forgetting the shutdown process

Call the API release function when your application exits. If you forget, resources may remain locked the next time it starts. In some cases this is not resolved until the development environment is restarted, so it is safest to write the shutdown code first.

Sensor values appear unstable

If the controlled target oscillates around the threshold, add the hysteresis described above. Also, for slow-responding targets such as thermal systems, simple on/off control causes overshoot. Control that approaches the target value gradually rather than changing abruptly will stabilize it.

Support / contract development

As an authorized distributor of these modules, Positive ONE provides supply and technical support in Japan.

• Selection advice — We propose suitable models based on the measurement target, accuracy, and installation environment.
• Configuration planning — We help you design the system, considering the number of sites and line conditions, to decide whether direct USB / network / callback is most appropriate.
• Operational verification — We support advance verification on actual hardware. Please also consult us to check whether use outside the specified range, such as outdoors or in high-temperature environments, is possible.
• Contract development — We can handle everything from developing data collection systems and GUI applications to integration into existing systems.
• Combination proposals — We can also propose a complete embedded system configuration combined with SOMs from our flagship brand Chinchilla.