New command line API

New command line API

Until now, when you wanted to test a Yoctopuce module, change a parameter, or read a sensor value, you had either to run a VirtualHub, or to write a short program yourself. From now on, there is a faster, simpler, and more efficient solution: the command line API...

The command line API is composed of a set of precompiled executables: one per type of functionality available in Yoctopuce USB modules, with an extra one to manage modules at a more global level. As usual, you do not need any driver, nor any setup program. You only need to download the library, copy the executables corresponding to your OS/architecture wherever you want, and you can start to play work.

Rather than going into a long and boring description of all the possibilities provided by this API, let's look at a few concrete examples. These examples make use of a Windows prompt, but they work in a strictly identical manner under Mac OS X and Linux, Intel as well as ARM.

Inventory
The first thing you'll probably want to do is to make an inventory of your modules. Nothing easier:


C:\>YModule inventory
YCO2MK01-05BB9       (My_co2_sensor)
RELAYHI1-00055       (Pumps_A)
RELAYLO1-02557       (Pumps_B)
TMPSENS1-05DE0
YBUTTON1-05ADD
C:\>
 


The effect of this command is to display the list of the serial numbers and logical names of the connected modules. Note that there are five connected modules, a Yocto-CO2, a Yocto-PowerRelay, a Yocto-Relay, a Yocto-Temperature, and finally a Yocto-Knob.

If you now want the list of the "relay" functions available on the group of connected modules, it's easy as well:


C:\>YRelay inventory
RELAYHI1-00055.relay1  (Pumps_A.pump1)
RELAYLO1-02557.relay2  (Pumps_B.relay2)
RELAYLO1-02557.relay1  (Pumps_B.relay1)
C:\>
 


You obtain a list comprising the relay of the Yocto-PowerRelay and the two relays of the Yocto-Relay.

Controlling the functions
Now, how to commute one of these relays? Dead easy:


C:\>YRelay RELAYHI1-00055.relay1 set_state B
OK: Pumps_A.pump1.set_state = 1
C:\>
 


Note that here we used the physical name of the relay, but we could have used its logical name instead:


C:\>YRelay pump1 set_state B
OK: Pumps_A.pump1.set_state = 1
C:\>
 


In a similar manner, you can retrieve the value of a sensor in the twinkling of a eye:


C:\>YTemperature TMPSENS1-05DE0.temperature get_currentvalue
OK: TMPSENS1-05DE0.temperature.get_currentValue = 24.1
C:\>
 


Using "any" and "all" aliases
The API also allows you to work on modules without necessarily knowing their names. For instance, if you use any instead of the function name, the command is executed on the first occurrence that is found.


C:\>YTemperature any get_currentvalue
OK: TMPSENS1-05DE0.temperature.get_currentValue = 24.1
C:\>
 


Inversely, you can address your commands to all the connected modules in one go. Here is how to create a Christmas tree in one line:


C:\>YModule all set_beacon ON
OK: My_co2_sensor.set_beacon = 1
OK: Pumps_A.set_beacon = 1
OK: Pumps_B.set_beacon = 1
OK: TMPSENS1-05DE0.set_beacon = 1
OK: YBUTTON1-05ADD.set_beacon = 1
C:\>
 


Remote control
Like regular APIs, the command line API can control modules remotely. You only need to provide the address of a machine on which a VirtualHub is running.


C:\>YModule -r 192.168.1.3 inventory
VIRTHUB0-7d1a86fb09
YCO2MK01-05BB9       (My_co2_sensor)
RELAYHI1-00055       (Pumps_A)
RELAYLO1-02557       (Pumps_B)
TMPSENS1-05DE0
YBUTTON1-05ADD
C:\>
 


Integrated help
If you don't remember how to use the API, no need to print a whole doc on dead trees: the API has its own integrated help. Simply use the /help parameter. For example, YModule /help or YModule set_beacon /help.

Conclusion
Frequent users of the Yoctopuce APIs will have noticed that the command line API maps rather faithfully the calls they are used to make in their own favorite programming language. Indeed, bar the exception of callback management, almost all of the functions available in standard APIs are available in the command line API. The exhaustive list of supported calls is available here.

Obviously, as for all of our APIs, the command line API sources are available free of charge.

If, after using the API, you notice that something is missing in the API, don't hesitate to contact Yoctopuce support, the support team will perhaps provide it for you.

Add a comment No comment yet
Back to blog












Yoctopuce, get your stuff connected.