Axis body worn solution
Body worn solutions from Axis capture valuable evidence. And they’re an effective way to deter bad behavior and positively influence the actions of camera wearers and the public alike. They record incidents as they appeared to the camera wearer, and as they sounded to all involved. They deliver recordings with high quality audio and video that you can use in internal investigations and in court.
Introduction
Get to know Axis body worn solution.
Plan your integration
Use cases and important considerations when integrating Axis body worn solution.
Develop your integration
Step-by-step guide and implementation recommendations.
Post integration considerations
Before you go and make those successful sales, we have some tips and considerations for you.
Introduction
About Axis body worn solution
Axis body worn solution - including the robust camera, docking stations and system controller - has been designed as an open system architecture, which allows for integration with video management systems (VMS) and evidence management systems (EMS), making the solution incredibly flexible.
You can plug Axis body worn solutions right into an Axis video management system or use your own preferred system. You can store video in the cloud or onsite.
Integrating Axis body worn solution
To help you build a strong integration with Axis body worn solution, we have developed trainings, API’s, code examples and important information about things you should consider when designing your integration. Follow the step-by-step guidelines below to learn more about suggested architecture, development examples and recommended considerations.
Get to know Axis body worn solution
The fastest way to get to know and get a good understanding of the Axis body worn solution is to read the introduction presentation and run the online training. You will learn about the components involved, the capabilities offered and various security aspects.
- Introduction presentation – for integration of Axis body worn (pdf)
- Run the online training
Plan your integration
The part you will integrate with is the system controller, AXIS W800, that pushes the recording files to you in MP4 or MKV format. The body worn camera will automatically send the files to the W800 when docked.
Important considerations
- The traditional driver implementation consists of sending requests to a camera. Here, your driver will act as a server that handles push requests.
- The controller creates body worn users and each recording it pushes to the VMS is associated with a user.
- The flow of recordings has one direction only. From the camera to the system controller and from the system controller to the VMS. After a successful transfer in each step, recordings are removed from the previous device. There is no turning back. It is up to the retention time, for how long you would like to keep the recordings.
- Please consider a licensing model related to body worn usage. We encourage the device-based licensing model, as this makes sharing of cameras cheaper.
Develop your integration
In order to integrate Axis body worn solution, you will need physical access to a system which consists of a system controller, a body worn camera and a docking station.
Once you are familiar with Axis body worn data flow, such as adding a user, assigning a camera and transfer of recordings, it is a good idea to try out the body worn integration example. We have used the same APIs covered in this section for integration of the body worn solution in AXIS Camera Station.
Hands on introduction
https://github.com/AxisCommunications/body-worn-integration-api
- Download the sample code (written in Golang) and have a look at the code to check how the containers are structured.
- To see the network protocol details, you may capture a network trace to see the flow.
- The Golang code works both for Windows and Linux, but in the example below we focus on how it runs on Windows.
Axis body worn Swift service example
- Build the example code
- Install Windows Axis body worn Swift service example
- Find the "Command Prompt" from Windows start menu, right click and choose "Run as administrator"
- Install Axis body worn Swift service example by changing the directory where "AxisBodyWornSwiftServiceExample.exe" is located in the command line window and enter the following command: AxisBodyWornSwiftServiceExample.exe install
- Follow the install instructions to configure Axis body worn Swift service example. For example:
- Create a username and password (You will not be able to see what you type as password)
- Enter storage location: Choose where you want to keep the recordings from the body worn system
- Choose the port to use or leave it empty to use 8080
- Choose IP address: 169.254.220.88 (Local Area Connection 1)
- Do you want to use HTTPS: y. (optional, for testing use HTTP instead of HTTPS)
- To get through the Windows firewall, you may need to open the port specified during the installation (default 8080)
- Note that the installation simply creates a file called settings.cfg in the same directory as the AxisBodyWornSwiftServiceExample.exe, which holds the information provided (storage location, port and IP address). When the program starts it expects settings.cfg to be located in the same folder, otherwise it will warn you that you have not completed the installation
- You can now run it as a service with the start command
- Run: AxisBodyWornSwiftServiceExample.exe start
- Stop: AxisBodyWornSwiftServiceExample.exe stop
- After installation it is possible to run the server without running as a service if you want to be able to see the logs directly in a terminal window. To do this, make sure you stop the service first and simply double click the AxisBodyWornSwiftServiceExample.exe file
- To uninstall the service run: AxisBodyWornSwiftServiceExample.exe uninstall
When run as a service, you should configure it to start automatically every time the computer boots.
The logs from the service are logged in Windows event viewer. You can type “event” in the windows search bar and run it. In the event viewer, choose Windows logs and then Applications. The logs will be listed under the application name AxisBodyWornSwiftServiceExample.
Location data integration
AxisBodyWornSwiftServiceExample contains a separate executable file that can demonstrate GPS trails. It is called "GNSSViewerExample" and it uses Leaflet and OpenStreetMap. This can be changed to google maps or any other geographical information system(GIS) tool easily. It can be done under cmd/index.html.
In order to use GNSSViewerExample, you must run the AxisBodyWornSwiftServiceExample first. Then you need to transfer recordings with the GPS trail information to your server. It will contain a file called "*_gpstrail.json". If you run the command "GNSSViewerExample_windows_amd64.exe Sample_gpstrail.json" it will open a port and ask you to select your browser to show it.
Sample cmd call:
View in the browser:
Get a connection file
The files will be created in the directory specified during installation. The system controller needs a JSON connection file which has to be supplied by the VMS. In the example code, it is located in the storage location specified during installation, named as config.json.
The Body Worn Manager handles all camera configuration. The data is pushed form the body worn system to the content destination. This is different from how you normally integrate with other Axis cameras. The VMS or EMS is acting like a server and listening for data that is pushed from the system controller. When transfer is complete, you will have all video and associated metadata, in the content destination, and it is deleted from the system controller.
All configuration of the system takes place outside the content destination, in the Body Worn Manager.
Server is configured, what should I do now?
After configuration, please try filming a few clips and offloading them to your server. You can use Wireshark to sniff the network and get API calls during the transfer.
To understand the file structures that the swift server creates, consult the documentation.
Signed video
With AXIS OS 11.0, Axis body worn systems got the capability of signed video (except AXIS W100). Signed video is available on other axis devices too, separate integration guidelines for signed video is available to you. In order to use the signed video in Axis body worn systems, you need to enable it via the capability API. After transferring the recording from the system controller you should keep the SEI frames in the content destination to verify the signing information.
Start implementing
You are now prepared to start your implementation. It is up to you to decide which programming language to use, but feel free to look at parts of the sample code and convert them to your choice of programming language.
Tips for implementation
- Axis body worn is designed to be used with HTTPS, however, during the first development phase it is better to use HTTP since encryption will make things complicated to debug.
- You can get video files in MP4 or MKV format, including Audio codec AAC (48kHz only). If you get your file in MKV format you can later on use the AXIS Media Control SDK to parse the data.
- You should pay attention on how you would like to store the metadata information, i.e. in XML or txt format. You probably want to have a strategy for storing the metadata and videos together. Do not forget to show interesting metadata to the user if needed.
- You should send “200 OK” to the system controller to complete the file transfer. The system controller will then delete the recording and you will own the data. So, before sending “200 OK”, make sure that the file transfer is completed, and that the file is not corrupt.
- Save and handle the data in your content destination. Once you have received the data, you need to handle it in a good and secure way.
- If your system is offline, the system controller will try to push data regularly and will keep the recordings until they are transferred.
Post integration considerations
If you have come this far, we would like to congratulate you on finishing your integration. Before you go and make those successful sales, we have some tips and considerations for you.
Upload speed
It is important to be aware of how quickly your server can handle uploads from system controllers. We recommend that you do some testing on relevant hardware to see which upload speeds you get. The maximum transfer speed of an AXIS W800 (System Controller) is 1Gbit/s.
For instance, let's say that your normal hardware setup measures 500Mbit/s for body worn offload. That would be fine for your customer that has 300 cameras that are used each day in three shifts. But If you have 100 cameras per shift, roughly 2 hours of recordings per camera in 1080 high bitrate is 100 x 2 x 5. (We are using 5 GByte per hour high bitrate in 1080p. It is just a good assumption ). That means you will get 1TByte of data per shift, and with 500Mbit/s that is a five hour offload time. You have to do it in less than 16 hours or eight hours before your next shift starts with the same hardware. If you have only 100Mbit/s and still 1TByte data per shift, then it will not be fine.
This consideration is important to test for and to take into account.
Importance of connection file
Except for the certificate, the same content destination requires the same connection file in order to continue to work as it should. Consider educating your end users that they cannot simply move a system controller to another instance of content destination without a proper system reset. This is a key feature of the system, and if you have implemented the StoreReadSystemID capability the body worn system will automatically block users from trying to change the connection file to a different system than what it was initially set up with.
You need to reset the body worn manager in order to change the content destination.
Tips for going forward
- Always test with the newest AXIS OS version (firmware). We are careful to keep the backwards combability, but like all other Axis products, we would like you to support our latest version.
- Per the above explanation about upload speed, it is good if you can give your customers some system performance recommendations.
We have prepared a list for you to verify your integration capabilities that consist of "Mandatory" and "Good to have" features:
| Use case description | Explanation | Importance |
| HTTPS support | ||
| Is HTTPS communication supported when communicating with Axis body worn system? | Mandatory | |
| Could HTTPS certificate be renewed when it needs to be updated, e.g. when the IP address of the server (where your application is running) is changed? | Mandatory | |
| Download connection file | ||
| Could the same connection file be used for multiple body worn systems connected to the same server (where your application is running)? | The connection file should not be uniquely created for a system controller by connecting to its serial number, for example. This makes system maintenance easier for large installations. | Good to have |
| Import data from body worn system | ||
| Is the default minimum retention period long enough, e.g. 90 days, to handle situations when people forget to dock camera for a long time? | This is to avoid the situation when recordings are removed right after they are uploaded. | Mandatory |
| Could the retention time of a recording be adjusted automatically based on its category? | Requires support for "Category" capability | Good to have |
| Would the users of your application be notified if there are problems with offloading recordings from the body worn system? | Good to have | |
| Would the users of your application be notified about newly arrived recordings of a certain category? | Requires support for "Category" capability | Good to have |
| Would the users of your application be able to import and decrypt a file? | In the bodyworn system it is possible to offload a stuck recording from the W800 to a USB stick. If your application supports encryption you should also be able to import this file and decrypt it. | Good to have |
| Are you using the signed video? | Axis Bodyworn System is designed for evidence management. Signed video provides end-to-end authentication from camera to client. | Good to have |
| Present body worn system data | ||
| Are recordings organized by camera user and not by physical cameras in your application? | So it's easy to find a camera user's recording if a physical camera is assigned to different camera users now and then, e.g. when BWS is set to self-assign mode. | Mandatory |
| Is the camera user name combined with the unique user ID (if configured in Body Worn Manager) as identifiers for cameras in your application? | For example, name the cameras by "Nice name (User ID)”. In case there are two camera users of the same name. Requires support for "StoreUserIDKey" capability. | Mandatory |
| Is the metadata of each recording presented in a user friendly manner? | In the form of bookmarks, for example. | Mandatory |
| Is it possible to search for recordings by metadata? | By searching for a category, location, trigger method, etc. | Good to have |
| Is a recording longer than minutes displayed as a single recording instead of multiple clips? | Mandatory | |
| Could the location data be used in a sensible way? | For example, by displaying recordings on a map, or possibility to search for recordings nearby a specified location, or at least allowing the location data to be copied and pasted so that the operator can find out where the recording was taken (by using a third party application, like Google Maps). | Good to have |
| Is the operator directed to the playback view in a friendly way when the live view for body worn camera is opened? | By displaying a body worn camera image or a friendly message that explains live view is not available for body worn cameras, for example. | Good to have |
| When playing back a recording, is the recording's trigger time (i.e. when the recording button is pressed) used as the default start point, instead of the beginning of the recording? | This is preferred because pre-buffer (by default on) recording is often not as interesting at first sight. It can be achieved by auto-generating bookmarks or thumbnails at the trigger time, for example. | Good to have |
| Are you showing the GPS trails of the devices during the recording time on a map? | Since Axis OS 11.1, Axis bodyworn solution can provide GPS trails as a part of the metadata that you can project on various maps. | Good to have |
| System maintenance | ||
| Is there any measure taken to stop users of your application from removing a body worn camera in your application before it's removed from Body Worn Manager? | This is to prevent complications caused by a mismatch between cameras in your applications and Body Worn Manager, e.g. license issues, leftover recording upload issues. | Mandatory |
| Does your application back up the body worn system related configurations regularly, together with the other important system configurations, e.g. username/userID/deviceID/systemID etc? | This helps the body worn system to restore the connection to your application in case of reinstallation of your application and prevents that you will have stuck content on your AXIS W800. | Good to have |
| Is it possible to show Body Worn Manager in a built-in browser in your application? | This way the system admin doesn't have to switch between Body Worn Manager and your application. | Good to have |
| Does your application notify its users if licenses for body worn system run out? | If licenses are based on camera users, licenses may run out when a new camera user is created in Body Worn Manager. | Good to have |
| Are body worn system related events logged in your application? | i.e. recordings from a body worn camera has arrived? | Mandatory |
| System performance | ||
| Has performance test been done on a system as large as you plan to support? | Recordings from body worn system need to be offloaded to your application in time. Otherwise, the system controllers and cameras can be filled up. As a result, the system won't be usable. | Mandatory |
| Documentation | ||
| Is there user documentation in place that explains how to integrate Axis Body Worn System with your application? | Please provide a PDF copy of your documentation to Axis. | Mandatory |
| Is there a webpage on your website that shows you have an integration with Axis Body Worn System? | Please provide a link to the page to Axis. | Good to have |
| Is it clearly documented from which body worn system firmware version your application has support for? | Mandatory | |
| Are the users of your application informed about this: Once the body worn system is set up to connect to one application, it is locked to that instance. A proper system reset is required if the system needs to be connected to another application instance. | Out of security reasons, the body worn system works only with the application instance with its SystemID. | Mandatory |
| Are the users of your application informed about this: Body worn system administration should be done in Body Worn Manager and not in your application. | Mandatory |