Skip to content

Commit ff81504

Browse files
traversarotraversaro
authored
Add first version of documentation and MATLAB-based helper library (#2)
1 parent 4bc6e8e commit ff81504

7 files changed

+197
-1
lines changed

‎README.md

Lines changed: 133 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,134 @@
11
# shinobi-robotics-research
2-
Files and documentation on how to use the Shinobi Open-Source Video Management Software for Robotics Research.
2+
Files and documentation on how to use the [Shinobi Open-Source Video Management Software](https://shinobi.video) for Robotics Research.
3+
4+
**This documentation are meant for installing a Shinobi instance on a private network, and do not convert the security implication of exposing a Shinobi instance on the public web.**
5+
6+
Table of Contents
7+
=================
8+
* [Install Shinobi](#install-shinobi)
9+
* [Access Shinobi and add Cameras](#access-shinobi-and-add-cameras)
10+
* [Automatic Start and Stop of Video Recording through Shinobi HTTP API](#automatic-start-and-stop-of-video-recording-through-shinobi-http-api)
11+
* [MATLAB](#matlab)
12+
* [Access Recorded Videos](#access-recorded-video)
13+
14+
## Install Shinobi
15+
16+
First of all, select a machine that will act as a [NVR (Network Video Recorder)](https://en.wikipedia.org/wiki/Network_video_recorder). As Shinobi is quite an invasive software as it requires to install custom dependencies at the system level, it is extremly recommended to use a dedicated machine, and to start from a vanilla installation of Ubuntu 20.04. To install Ubuntu 20.04 on a new machine, please check the docs in https://ubuntu.com/tutorials/install-ubuntu-desktop .
17+
18+
Once you installed Ubuntu 20.04 on the machine, install Shinobi following the docs in https://shinobi.video/docs/start . The recommended installation strategy ("The Ninja Way") involve downloading and executing a script from the network, so make sure that the script is not doing anything dangerous from the safety and the security point of view. For all options, choose the default choice.
19+
20+
## Access Shinobi and add Cameras
21+
22+
Once you installed Shinobi you should be able to access it on `http://<ip_address>:8080` if you used the default settings, and you can access the admin interface at `http://<ip_address>:8080/super`. At this point, you can add to Shinobi all the cameras (that are called **monitors**, in Shinobi/CCTV jargon) that you want to use, following the official Shinobi docs at https://shinobi.video/docs/configure . If you correctly added two cameras and you enabled them, you should see something like this in Shinobi interface:
23+
24+
![shinobi_example](https://user-images.githubusercontent.com/1857049/127281442-a9c4deab-2411-498e-be09-517c165ad1fb.png)
25+
26+
Once you setup your cameras in Shinobi, you can then configure the Shinobi API to enable remote control of recording of the camera.
27+
28+
## Automatic Start and Stop of Video Recording through Shinobi HTTP API
29+
30+
The Shinobi API is documented in https://shinobi.video/docs/api . It is a standard HTTP API, that can be access by any system with a working HTTP client, so basically any programming language. It can be used to start and stop recording of the video camera
31+
32+
To access the Shinobi API of a given Shinobi instance, you need the following info:
33+
* IP and Port in which Shinobi is available (`[ADDRESS]`). Example: `http://10.0.0.1:8080/`
34+
* API Key (`[API KEY]`). Example: `VwRCagLeIypSiEzp9LkKAZnCZ7rb46`
35+
* Group Key (`[GROUP KEY]`): Example: `wuio1HKFc1`
36+
37+
The Shinobi URL is the same one used to access Shinobi from the browser, while the API Key can be created and accessed via the API entry of Shinobi menu, while the Group Key can be found in "Settings".
38+
39+
Once you have this info, you can check that they are correct and get the list of active camera (aka monitors, in CCTV/Shinobi jargon) and its details in json format accessing simply from a browser:
40+
~~~
41+
http://[ADDRESS]/[API KEY]/monitor/[GROUP KEY]
42+
~~~
43+
44+
If that it is working, you can save this info on your system by creating a `shinobi-robotics-research-info.json` in your Home directory (`~` on Unix systems, `%HOME%` on Windows), with the necessary content:
45+
~~~
46+
{
47+
"shinobi_url": "http://10.0.0.1:8080",
48+
"shinobi_api_key": "VwRCagLeIypSiEzp9LkKAZnCZ7rb46",
49+
"shinobi_group_key": "wuio1HKFc1"
50+
}
51+
~~~
52+
53+
The Shinobi HTTP API can then be used with this data to automatically start and stop camera recording. While accessing HTTP servers is a capability
54+
provided in most programming languages and environments, as part of this repo we provide some helper libraries.
55+
56+
The helper libraries are available in the following languages:
57+
58+
* [MATLAB](#MATLAB)
59+
60+
### MATLAB
61+
62+
#### Installation
63+
64+
First of all, clone this repo:
65+
~~~
66+
git clone https://github.com/dic-iit/shinobi-robotics-research
67+
~~~
68+
69+
Then, add the `shinobi-robotics-research/matlab` directory to the [MATLAB search path](https://www.mathworks.com/help/matlab/matlab_env/what-is-the-matlab-search-path.html), using one of the available method. For example, you can simply add the directory to `MATLABPATH` environment variable and then launch `MATLAB`:
70+
~~~
71+
export MATLABPATH=$MATLABPATH:<location-where-you-cloned>/shinobi-robotics-research>/matlab
72+
matlab
73+
~~~
74+
75+
#### Example Usage
76+
77+
~~~matlab
78+
# Get Shinobi instance information from shinobi-robotics-research-info.json file
79+
shinobi_info = srr.load_info();
80+
# Get camera from the Shinobi server
81+
cameras_info = srr.get_available_cameras();
82+
83+
# Start camera recording
84+
srr.start_video_recording(shinobi_info, cameras_info)
85+
86+
87+
# Do experiment
88+
# ...
89+
90+
# Stop camera recording
91+
srr.stop_video_recording(shinobi_info, cameras_info)
92+
~~~
93+
94+
95+
#### Detailed Documentation
96+
97+
##### `srr.load_info()`
98+
99+
The information on the specific Shinobi instance can be read from the `shinobi-robotics-research-info.json` file in the home directory.
100+
~~~
101+
>> shinobi_info = srr.load_info()
102+
103+
shinobi_info =
104+
105+
struct with fields:
106+
107+
shinobi_url: 'http://10.0.0.1:8080'
108+
shinobi_api_key: 'VwRCagLeIypSiEzp9LkKAZnCZ7rb46'
109+
shinobi_group_key: 'wuio1HKFc1'
110+
~~~
111+
112+
The values of this structure can also be set directly in the code, even if this is tipically not recommended as this kind of metadata is setup-specific:
113+
~~~
114+
shinobi_info_hardcoded.shinobi_url = 'http://10.0.0.1:8080';
115+
shinobi_info_hardcoded.shinobi_api_key = 'VwRCagLeIypSiEzp9LkKAZnCZ7rb46';
116+
shinobi_info_hardcoded.shinobi_group_key = 'wuio1HKFc1';
117+
~~~
118+
119+
All other methods will take in input an instance of this info structure.
120+
121+
122+
## Access recorded video
123+
124+
The video recorded by Shinobi are then available directly from the Shinobi web ui, see for example (in this case, I had recorded 4 videos):
125+
126+
![shinobi_access_video1](https://user-images.githubusercontent.com/1857049/127284398-dc0c6271-f77a-4b8b-99aa-f7336dbd9497.png)
127+
![shinobi_access_video2](https://user-images.githubusercontent.com/1857049/127284392-829a5820-c9ed-4272-bf06-87b1518d4819.png)
128+
![shinobi_access_video3](https://user-images.githubusercontent.com/1857049/127284380-d3c228e1-6cbc-47db-b231-65e4658d6e29.png)
129+
![shinobi_access_video4](https://user-images.githubusercontent.com/1857049/127284376-c4577756-2dff-45bb-a6f8-0ee4edfa6524.png)
130+
131+
132+
Furthermore, the video can be also accessed, downloaded and deleted via Shinobi HTTP API as well, see https://shinobi.video/docs/api#content-modifying-a-video-or-deleting-it . This can be useful to then automatically transfer videos to another location once the experiments are done, but this
133+
functionality is not provided in the helper libraries provided in this repo, as tipically the storage backend may vary from research lab to research lab.
134+
However, the already provided helper libraries can be used to understand how to access the HTTP API from the selected language.

‎matlab/+srr/get_available_cameras.m

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
function [cameras, status] = get_available_cameras(srr_info)
2+
%GET_AVAILABLE_CAMERAS Get the available cameras in the shinobi server
3+
4+
5+
% Build HTTP query to get status
6+
% https://shinobi.video/docs/api#content-get-all-saved-monitors
7+
% https://www.mathworks.com/help/matlab/ref/matlab.net.http.requestmessage.send.html
8+
r = matlab.net.http.RequestMessage;
9+
uri_raw = sprintf('%s/%s/monitor/%s', srr_info.shinobi_url, srr_info.shinobi_api_key, srr_info.shinobi_group_key)
10+
uri = matlab.net.URI(uri_raw);
11+
resp = send(r,uri);
12+
status = resp.StatusCode;
13+
cameras = resp.Body.Data;
14+
15+
cameras = srr.simplify_cameras_metadata(cameras);
16+
17+
end
18+

‎matlab/+srr/get_home_dir.m

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
function [home_dir] = get_home_dir()
2+
%GET_HOME_DIR Return home directory of the user
3+
home_dir = getenv('HOME');
4+
end
5+

‎matlab/+srr/load_info.m

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
function [srr_info] = load_info()
2+
%load_info Load shinobi server info from the default configuration file
3+
4+
% Get default configuration file
5+
conf_file = fullfile(srr.get_home_dir(),'shinobi-robotics-research-info.json');
6+
conf_file_content = fileread(conf_file);
7+
srr_info = jsondecode(conf_file_content);
8+
9+
end
10+

‎matlab/+srr/simplify_cameras_metadata.m

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
function [outcameras] = simplify_cameras_metadata(incameras)
2+
%simplify_cameras_metadata Remove all the metadata except for mid and name
3+
for k = 1:numel(incameras)
4+
outcameras(k).mid = incameras(k).mid;
5+
outcameras(k).name = incameras(k).name;
6+
end
7+

‎matlab/+srr/start_video_recording.m

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
function [status] = start_video_recording(server_info, cameras)
2+
%START_VIDEO_RECORDING Start the video recording
3+
for k = 1:numel(cameras)
4+
% https://shinobi.video/docs/api#content-set-to-a-mode-for-a-monitor
5+
r = matlab.net.http.RequestMessage;
6+
uri_raw = sprintf('%s/%s/monitor/%s/%s/record', server_info.shinobi_url, server_info.shinobi_api_key, server_info.shinobi_group_key, cameras(k).mid)
7+
uri = matlab.net.URI(uri_raw);
8+
resp = send(r,uri);
9+
end
10+
11+
end
12+

‎matlab/+srr/stop_video_recording.m

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
function [status] = stop_video_recording(server_info, cameras)
2+
%STOP_VIDEO_RECORDING Stop the video recording
3+
for k = 1:numel(cameras)
4+
% https://shinobi.video/docs/api#content-set-to-a-mode-for-a-monitor
5+
r = matlab.net.http.RequestMessage;
6+
uri_raw = sprintf('%s/%s/monitor/%s/%s/start', server_info.shinobi_url, server_info.shinobi_api_key, server_info.shinobi_group_key, cameras(k).mid)
7+
uri = matlab.net.URI(uri_raw);
8+
resp = send(r,uri);
9+
end
10+
status = true;
11+
end
12+

0 commit comments

Comments
 (0)