Development kit versions
Currently available we have two development kit versions.
Version 2.1 is a wired kit that resembles a sound bar (the earlier versions are similar but they do have a true SoundBar functionality as well). The quick guide applies to this development kit.
Version 2.5 is a wireless kit composed by battery powered sensors (normally 5) and one wireless controller. While some of this guide still applies (everything related to protocol, examples, web guide and API), we advice this kit only to advance users and also suggest to get in touch with us in order to be informed on how to get started with it.
Mounting the kit (version 2.1 only)
Some assembly is required first. Your kit is composed of three parts and it is requires an additional USB supply (5v 1A). You can also simply slot the parts together without fastening with the supplied screws. We do advance against it until you do not feel fairly competent on what the kit can do.
The video on the right illustrated how to mount the kit, step by step. You will need a slot-head screwdriver
First connection to the development kit
Now that the kit is complete, it is time to use it. First two important warnings:
-> IF YOUR KIT HAS ETHERNET PORTS, THEY ARE NOT TRUE ETHERNET PORTS. DO NOT CONNECT THEM TO A ROUTER OR OTHERT DEVICES. YOU RISK BREAKING THE DEVICE ITSELF.
-> THE DEVICE BY DEFAULT WILL INITIALLY ONLY MONITOR AN AREA OF 4M X 4M IN FRONT OF THE DEVICE ITSELF.
Let’s now get started. Power the kit connecting a standard USB supply or battery pack preferably to the USB 1 (see video).
The first time you do so, the device will be in the Access Point mode. A WiFi network called “Xetal_something” will be created. Connect to it and navigate with your browser to the IP 192.168.76.1. Follow the instructions on the displayed pages to set up password, change the network name and/or connect the device to a local network.
You will need to know the device IP (or DNS name) to use any provided software and examples. The device uses by default ports 2005 and 6666. Make sure your network does not block them. The ports can be changed programmatically (see the code and API you are using) in case you need to use different ones.
First test and use
This section applies only if your device has firmware version January2018 or newer. In this case, after having provided the password, the home page will look slightly different. At the bottom of the login section, it will also provide a link to the XetalApps. Click the link in order to access some of the functionality directly from the web browser without the need for any API or code.
You will be provided a screen with several options. On the top row, you will find the three applications: a CAD for room drawing and check, a Sensor Editor to place and verify placement in the room of sensors and a tracking client. The first two applications are useful for the installation of any Kinsei device in a. given room. Please refer to the source code repository for further information. The third application implement a complete client for detection, counting and tracking of people. It is best to click on it to check that the device works correctly (if you do not get a page with a blue room and moving dots, the device is not working properly)
In the second row we find three links. The first enables the JSON client (enabled by default), the second disabled it and the third displays the current configuration file. Please note that the status of the JSON server is persistent also after reboot or power down.
Finally at the very bottom, you will find the link to the JSON feed. Clicking on this link will displays the latest JSON data form the device. Please refer to the JSON documentation for an explanation of the data displayed.
Firmware, API and alike
To get you started, we have prepared several examples and utilities next to dedicated API. We release and constantly update everything on the xetal repositories. Please pay attention to the documentation (comments) in the code itself and the README.md file. If an examples does not ask for the device IP, make sure you change it in the code itself. If the software does not to work, make sure you have the latest firmware. When nothing works just contact us.
All API and examples are released in their source code under a MIT license, if not otherwise indicated in the repository itself.
The firmware itself is provided pre-compiled and it is released also on the repository page under a proprietary licence. If you believe you have found a bug, inform us ASAP.
We also provide tools for installation and optimisation, as well as the images of the LEDE distribution used int he device. These software are released under a GPL (3 and 2) license.
Remember, if you need something that is not available, contact us and we will see if we can add it asap!
How to connect programmatically without API
We currently provide three ways of connecting to the device to retrieve data which is not based on using any of the available API. In order of performance:
TCP on port 2005. This is the communication protocol used by our API and you can find a description of every valid TCP command in the ‘doc’ folder of every API repository, for example in the Python-API. We have two TCP server on the device for retrieving data and for ruin-time tuning. Please refer to the documentation on the repo for further information.
MODBUS on port 1502. The device (firmware January2018 and newer) has a MODBUS client included in the ModBusfirmware. The client is by default disabled and can be enabled by means of a standard CGI link. You can find more information about the coil/register mapping of the device as well as how to enable and disable the MODBUS client service in the README file of the associated repository.
JSON. A JSON server is included and turned on by default as well (firmware January2018 and newer) . In order to access it refer to the above section “first test and use”.
Changing and tuning the kit to your needs
Apart from an API for the monitoring people and temperature, we also provide an API and associated tools for the set-up and optimization of the kit itself. As this is rather advanced usage, we encourage you to take contact with us for a FREE call in which we give you an explanation of the parameters you can use. As a short introduction:
Set-up
In the Python API you can find an application in the tuner folder called configurator.py that allows to retrieve and modify the configuration file of the device itself. The file has enough comments for you to understand how to use it. In case you want to change the monitored area (into anything polygonal), precision, maximum detected speed, position of sensors, etc. this is something you need to use.
In the GitHub you will find the repo JS-Workbench, which contains a javascript application that allows to define the monitored area, place sensors and execute some basic tracking all from a browser. At the time of writing the application is in development and some features might still be absent or unstable. However, the current pre-release is good enough already to be used to simplify the definition of the monitored area and placement of sensors. When fully released this application will be available or installable directly on your device.
Optimisation
In the Python API you can fine an application in the tuner folder called tuner.py that is an example of using the tuner server of the device (available also via the Python and C++ API). This application shows how the API can be used to modify several parameters while the device is active in order to optimise the device itself and even build closed loop systems. Refer to the API documentation as well as the help text in the tuner.py itself tom understand what parameter does what.
Reset Procedure
In case the kit is connected to your own network and you need to use it back in AP mode or to connect it to another WIFI network, please reset the device as follows:
With the device ON press the RESET button (there is only one button on the central unit) using a pen or similar for at least 10 seconds to only reset the wifi connection or at least 20 seconds to do a full factory reset. The latter also removes the password top the device itself and brings the kit in its factory mode.
In both cases refer to the first use steps after any of the two resets.
Update the kit
To update the firmware/OS , please follow the procedure described in this document:
http://xetal.ddns.net:81/Kinsei/Tracking/Xetal7688/KinseiTracking-firmware-bin
To update the Kinsey tracking server, please follow the procedure described in this document:
Debugging the kit with the LEDs
The central unit is provided with 6 status LEDs that are useful to understand what is the WiFi status and if there are issues and even have an idea of what the issue might be. Starting from the top LED in the photo we find:
pled is the power led and it must be on when the unit is powered.
wled is on if the kit is in Access Point mode
led0 is one during the factory reset procedure
led1 is on during the normal reset procedure
green is on and blinking if the tracking server is active. The blinking rate is the same as the rate at which the kit is sampling data from the sensors. If the led is off or not blinking (and the green led is on/blinking) there is a problem with the tracking server. It is either in block or is is not running at all.
red is on and blinking if the sensors are connected correctly and the rate is the same as for the green led. If the led is not blinking or it is off, there is a problem with one of the sensors (badly connected or broken)
