← Back to Articles

 

(Tested on Linux 5.15.0 platform)

Xeoma works well with a connected USB game controller, or Joystick

The controller must be recognized by the system, to be able to load the appropriate driver (kernel module). The command “lsusb” gives us information about that. The device should be listed.

Next some packages are to install. The packages “joystick” and “jstest-gtk”.

Command line tools, included in “joystick” package, are jscal, jscal-store, jscal-restore and jstest. “jstest-gtk” is just a GUI, using jstest and jscal for tests and calibration.

REMEMBER! Linux offers just one unified driver for a wide range of USB joysticks and game controllers compared to a Windows environment, with manufacturer drivers for many different controller types.

There are many low cost game controllers available, that will probably all work instantly in most modern Linux distributions. But there are also expensive and extremely precise USB Joysticks, that may not work perfect in Linux, when using first time.

Not many surveillance systems offer the possibility to use USB Joysticks or USB game controllers for PTZ control. Xeoma does! It just depends on a properly installed device.

 

 

It is important to check, via “jstest-gtk”, if the axles work intependently. That means, to watch the tool’s test interface, while moving i.e. the x axle (Axis 0) from the left/max position to the right/max position several times. This movement should not affect the y axle (Axis 1). It’s easy to observe this graphically in “jstest-gtk”.

If using a Linux supported controller that has 4 buttons for left/right and up/down movement (like the software PTZ control inside Xeoma), there is no problem. Then it is not necessary to read this article to its end. The controller should work out of the box in Xeoma.

If using a one stick (no direction buttons) steering solution, it’s possible to make moves BETWEEN Axis 0 and Axis 1.

In example, if you move a single stick game controller from zero, to a position, between 1 and 2 o’clock, means the same, as if you would push two buttons of a 4 button, 4 directions controller at the same time. In our 1,5 o’clock example, the up and the right arrow.

In the best case there would be a diagonal move of the cam. But the cam won’t move like that. Also not in Windows environment. Not even when using the “virtual joystick” of a manufacturer app for smartphones or tablets. Tested via Hik-Connect on a Hikvision device. It moves left/right OR up/down.

If your joystick device leads to uncontrolled behavior of your cam, inside Xeoma, it probably creates a mix of x and y coordinates, because you cannot push the joystick exactly to one of the four directions, like in the software PTZ control of Xeoma.

Cheap or less precise controllers may work at once, precise controllers probably won’t.
In any case, after having read the above, we know the reason for uncontrolled camera movement.

There is a solution to modify the behavior of the joystick device, by telling the driver different values, than the standard ones. In short words, the travel of the axles must be reduced and the room for the controller’s zero position enlarged. This is possible via “jstest-gtk”.

We’ve got to play around with the values and check the behavior in the test interface until we are sure that Axis 0 movement does not affect Axis 1 and vice versa.

After having found the best values, we should pin them in a config file, or the values are gone by the next restart or plugging process of the device!

At this point we change to the command line interface as ”root”.
Means all the following must be done as superuser.

There is a tool to do the required job, called “jscal-store”. It creates a configuration file of the actual configuration, called “joystick.state” in the /var/lib/joystick folder.

REMEMBER: Do this immediately after you have successfully adjusted the joystick for your needs with “jstest-gtk” as user. Don’t restart, Don’t unplug!

As root: jscal-store /dev/input/js? (Replace the ? With the correct device number on your system)

After that, the file /var/lib/joystick/joystick.state is created including the values we have set. NOTE: The file can also be edited manually. Superuser (root) can enter desired values directly and save them.

After having changed some values in the file manually, we’ve got to transmit them to the device.

As root: jscal-restore /dev/input/js? (Replace the ? With the correct device number on your system) The settings for the device remain after restarting the system, or unplug and plug it again.

By Ralf

August 13, 2024

Read also:
Additional modules in Xeoma: artificial intelligence and more refined features
PTZ Tracking for PTZ security cameras in video surveillance systems
Setting up PTZ guard tour in Xeoma
Additional module in Xeoma: Move to PTZ preset