← Back to Articles

Control Xeoma using JSON: the whats and hows

Sources Filters Destinations

What do we know about automation? The main idea behind it is to make various programs and devices cooperate with each other to raise their overall effectiveness, especially without human interference. This is much like a well-trained choir where each member gets a tune of their own, and yet together they comprise a wholesome musical. Home automation is an example familiar to many by now, and those who haven’t dipped their toes into this topic yet are quite likely to do so eventually.

How exactly such automation works is a questions without a clearly defined answer – almost every such system is quite unique and needs to be studied individually. This is where things like APIs, common protocols and integration options become invaluable. Among the common protocols often used for web-based integration one will quickly find JSON – JavaScript Object Notation – a simple, yet robust, format that became XML’s more successful younger brother.
And now Xeoma has learned how to work with it too.

So, what exactly can you do with Xeoma using JSON? You can control the very bones of the system – its modules, all of them. This is best demonstrated with examples.

Suppose we have a couple of cameras added to our server:

Their respective chains look like this:

The easiest way to look at how this API works is to use a Google Chrome extension called “Tabbed Postman – REST Client”. There are 2 main reasons for that:

  1. GET requests can be sent via a browser normally, but the response is going to look rather cluttered. The extension makes it more readable for a human eye.
  2. POST requests can’t be sent via a browser but can be sent via the OS’s own means (e.g. curl). The problem, however, is that this method requires rather in-depth knowledge of the command structures and proficiency with command-line interface. The extension is far more newbie-friendly.

To clarify: GET requests are basically questions that Xeoma will answer; POST requests are instructions that Xeoma will follow. For simplicity’s sake, we’ll send the commands to the same machine the browser is working on, but you can use them remotely too, as long as the relevant port is available (10090 by default).

The first such command asks Xeoma to give a list of modules currently in use on the server:

http://IP:10090/api?login=USERNAME&password=PWD&modules=

IP – the server’s IP-address (localhost for the same machine);
USERNAME – the user’s name in Xeoma (the main admin always has the name Administrator);
PWD – that user’s password.

Here is what it will look like in the Postman:

Once we hit Send button, the response will be (be sure to choose JSON and Pretty in the parameters):

These are both our chains (each enclosed in {}), module-by-module. The name of the camera is also indicated here to identify the right camera more easily (particularly useful when several cameras have identical chains).

The second command asks Xeoma about the current settings for one of the modules:

http://IP:10090/api?login=USERNAME&password=PWD&settings=MODULE_ID&get=

MODULE_ID – the unique name of the module. Remember the numbered names from Xeoma’s response to the previous command (e.g. Date.Marking.13)? That’s the ID.

The full URL will look something like this:

This time we get a more verbose response:

The easiest way to read this is to take a look at the type parameter. The common types are:

  • Label – a text message, usually explains what the next object does. Cannot be changed.
  • EditBox – a box for text the user can edit directly. Can be changed.
  • ComboBox – a drop-down list or slider. Note that they often have the parameter translatedValues – these are NOT the actual parameters you can change, they are always listed separately as values. Can be changed.
  • EditableComboBox – a drop-down list the user can edit. Can be changed.
  • CheckBox – a box the user can tick or untick. Can be changed.
  • ImageAreaSelector – a drawing board for detectors that allow the user to specify an area. Can be changed.
  • ProgressBar – a bar showing percentage between 0 and 100. Cannot be changed.
  • UndefinedType – a link to a web-page, does not show up in the browser (we’ll come back to that a bit later). Cannot be changed.

Finally, there is a command that instructs Xeoma (POST) to change the settings of a given module. This is where it gets tricky: we need both the URL and the parameters that we want to change. The command itself is:

http://IP:10090/api?login=USERNAME&password=PWD&settings=MODULE_ID&set=

The parameters and their values are:

{
“parameter1_name”:“parameter1_value”,
“parameter2_name”:“parameter2_value”,

}

Parameter names come from “id” values in the previous command’s response (each object has its own).
Here is an example:

N.B. Be sure to choose POST as the command type, and raw and Text under the URL. Mind the small and capital letters, quotes, commas and colons. Every symbol counts here.

If everything is done correctly, the response will be:

The new settings were successfully applied and saved.

Otherwise, you will see something like this:

This usually indicates an error in the command syntax, check the raw text thoroughly.

Controlling most objects is pretty self-explanatory (e.g. CheckBoxes can be true or false, EditBoxes allow any kind of text (single-line or multi-line), etc.) but ImageAreaSelectors require special attention. To “draw” an area using JSON, you will need to use 1 and 0, where zeros are pixels that are not inside the detection area, and ones are pixels inside that area. First, we need to establish the scale for the drawing in pixels via detectionAreaWidth and detectionAreaHeight (similar to e.g. canvas size in Photoshop). Suppose we want it to be a rectangle 6×4:
"detectionAreaWidth":6
"detectionAreaHeight":4

An empty area, without any detection zone at all, will look like this then:
000000
000000
000000
000000

Now we add ones to draw an area we want:
001111
001111
000111
000111

Deleting all indentations will give us this command:

Here is our brand new detection zone:

Now let’s try changing the settings for a different module – Marking. We want to alter the text, its position and size:

All done:

As we’ve mentioned before, JSON is most commonly used for web-based integration, making it ideal for working with web-pages. One last command Xeoma now understands allows to generate a full web-page with the given module’s settings:

http://IP:10090/api?login=USERNAME&password=PWD&settings=MODULE_ID

This is where we go back to the UndefinedType – objects with this type are not displayed on the resulting page, but are necessary to keep all other objects properly aligned:

This works for every module, all changes will be applied to the server, once the Save button at the bottom is pressed.
If you are a web-developer, you probably already know what’s coming. Yes, since every part of this page (labels, boxes, etc.) is its own object, they can be taken from it, rearranged and placed on your own web-page to suit your needs or the needs of your clients.

“Hold on!” you might say. “Doesn’t this create a huge security hole? Surely, if a hacker decides to do their homework and study this API, then all that’s left to do is find my password – and my video surveillance server is at their mercy.”
We’ve considered this and here are several ways to secure this side of Xeoma:

  1. First and foremost, you can use Apache as your shield (not the Native Americans, this Apache). This article describes exactly how.
  2. The API uses Xeoma’s web-port (10090) to pass the commands to the server, but you can assign a completely different port to it via the Web Server module.
  3. If you have this port accessible from external networks, you can also set restrictions and rules on the router’s firewall to prevent any unwanted visitors from reaching the server.

Finally, as you may have noticed, the names for different modules do not always coincide with the ones you can find in the application. Here you can find a table with all the modules and their proper names for your convenience:

Module Name JSON name
SOURCES
Universal Camera UniversalCamera
Microphone AudioSource
Screen Capture ScreenCapture
File Reading FileInput
Another Xeoma WebConnectorReceiver
FTP Receiver FTPReceiver
HTTP Receiver HttpReceiver
FILTERS
Motion Detector MotionDetector
PTZ Tracking PtzTracking
Senstar PTZ Tracking SenstarPtz
Visitors Counter VisitorsCounter
Object Detector ObjectDetector
Scheduler Scheduler
Marking DateMarking
Privacy Masking AreaCensor
Fisheye Dewarping FisheyeUnwraper
Button Switcher ButtonSwitcher
Day Detector NightBlocker
HTTP Switcher HttpSwitcher
HTTP Marking HttpMarking
Sound Detector AudioDetector
Image Rotate ImageTurn
ANPR AutoNumberPlateRecognition
Problems Detector ProblemsDetector
Face Detector FaceDetector
Unitor ImageMerger
Image Resize ImageResize
Image Crop ImageCropping
Detector of abandoned objects AbandonedObjectsDetector
Smoke Detector SmokeDetector
Cross-line Detector CrossLineDetector
Loitering Detector LoiteringDetector
Relay Switch RelaySwitch
Condition Condition
DESTINATIONS
Preview Preview
Preview and Archive Preview%2BArchive
Save to File FileOutput
Sending Email Email
SMS Sending SmsSender
Web Server WebconnectorTransmitter
RTSP Broadcasting RtspTranslator
FTP Upload FtpOutput
HTTP upload to other Xeoma HttpOutput
Sound Alarm AlarmSound
Application Runner AppRunner
HTTP Request Sender HttpRequestSender
Pop-up Window (in Client) ClientWindowPopup
ANPR Sender to FTP AnprFtpUploader

October, 5 2018

Read also:
API for integration of Xeoma
Integration example: Xeoma and Telegram