-
Notifications
You must be signed in to change notification settings - Fork 18
Integration best practices
Over some time, we have identified a collection of the most frequent pains that Arrow integrators must face. This document explains these problems step-by-step and it should help you to deal with them. You can also contact us directly if you find anything that is not covered by this document.
The Arrow Client generates two configuration files on its first start. Among other things, the configuration files contain a unique identifier of the client. It is essential to store the configuration files in a persistent storage. Otherwise, the identifier will be lost on every reboot of your device. By default, the configuration files are stored in /etc/arrow. You can change the location by using the --config-file and --config-file-skel parameters, e.g.:
arrow-client arr-rs.angelcam.com:8900 \
... \
--config-file=/my/location/config.json \
--config-file-skel=/my/location/config-skel.json \
...
As already mentioned, the configuration files contain a unique identifier of the client. If you include the configuration files in your firmware, all your devices will share the same identifier. Our servers will not be able to distinguish your devices and the devices will disconnect each other from our cloud.
When refurbishing and re-selling used devices, you need to make sure that the devices cannot be accessed by their former owners anymore. Factory reset is the ideal way how to do this. Make sure that the Arrow Client configuration file gets deleted on factory reset of your device. It is the only secure way how to make sure that refurbished devices can no longer be accessed by their former owners.
If your device has more than one network interface, it is important to tell the Arrow Client which network interface should be used for the device identification during the pairing procedure. Our servers do not know the unique identifier generated by the client until the pairing procedure is complete. Therefore, we need users to enter MAC addresses of the paired devices. It is up to you to choose which MAC address should be used for pairing if there are multiple network interfaces.
For example, let's suppose your device has the following network interfaces:
- eth0 with MAC address 00:00:00:00:00:00
- wlan0 with MAC address 11:11:11:11:11:11
00:00:00:00:00:00 will be used for pairing, if you start the Arrow Client like this:
arrow-client arr-rs.angelcam.com:8900 -i eth0 ...
and 11:11:11:11:11:11 will be used for pairing, if you start the Arrow Client like this:
arrow-client arr-rs.angelcam.com:8900 -i wlan0 ...
Although we do not prohibit using other than localhost IP addresses, we strongly encourage you to use the localhost IP address for all services passed as command line arguments. Using an IP address of a physical network interface is problematic because the IP address can change. Internally, every service is identified by a numeric identifier generated by the Arrow Client. If the IP address changes, a new identifier is generated. The Arrow Client simply takes it as a different service. Therefore, changing the IP address may result in the following situations:
- If the IP address changes after the Arrow Client gets started, the client will not be able to communicate with given services. It will use the old IP address.
- If the IP address changes after the device is paired with an Angelcam account, the corresponding streams will stop working with Angelcam because their identifiers get changed as well.
- The Arrow Client remembers all stream URLs passed to it as command line arguments. As a result, you will see multiple cameras on the https://my.angelcam.com/connect page, one for every IP address that has been assigned to the network interface.
For example, let's say you have a device with one network interface and an RTSP server with a single H.264 stream. The network interface have IP address 192.168.1.100, the RTSP server is on port 554 and the stream is available on /live/sdp.
This is a wrong way how to start the Arrow Client:
arrow-client arr-rs.angelcam.com:8900 \
... \
-r rtsp://192.168.1.100/live/sdp \
...
This is the preferred way:
arrow-client arr-rs.angelcam.com:8900 \
... \
-r rtsp://127.0.0.1/live/sdp \
...
The Angelcam web can work as a proxy for web interface of your device. This way, you will let your users access the web interface without even knowing IP address of their camera. Moreover, they will be able to access the web interface remotely over the Internet. The only thing you have to do is to start the Arrow Client with one more parameter. You need to tell the Arrow Client the port and the IP address of the corresponding HTTP server. The IP address must be the same one as you use in the stream URL. For example:
arrow-client arr-rs.angelcam.com:8900 \
... \
-r rtsp://127.0.0.1/live/sdp \
-h 127.0.0.1:80 \
...
Make sure that the system time in your device is set correctly before starting the Arrow Client. (You can use some of the free NTP services for example.) If you start the Arrow Client with invalid system time, the certificate validation will fail and the client will not be able to connect to Angelcam.
To make your device really plug and play, you should make sure that the DHCP client is enabled by default in your device.
It is highly recommended to give your customers access to the logs produced by the Arrow Client (e.g. in a web interface of your device). It will help you, your customers and our support team to diagnose potential connection problems. By default, the Arrow Client sends all its log messages into syslog. You can switch it to the standard error output using the --log-stderr or --log-stderr-pretty parameters.
Even though all MAC addresses should be unique by definition, we have already seen a few cases where devices shared their MAC addresses. MAC addresses are used as identifiers for pairing Arrow devices, so it is really important for your devices to use MAC addresses assigned from your own private range and, most importantly, none of your devices may share a single MAC address.
Despite the fact that the process of pairing Arrow devices has been designed specifically to prevent attackers from hijacking cameras by guessing their MAC addresses, having more not-yet-paired devices sharing a single MAC address could cause some serious issues to the pairing process. In order to keep Angelcam services as secure as possible, Angelcam servers will temporarily reject all connections from a specific MAC address whenever multiple devices with the same MAC address are detected. This security measure will not affect devices that have been already paired with an Angelcam account.
If possible, add a link to the web admin of your device that will simplify pairing with Angelcam Cloud for end users. Pairing using this link does not require entering MAC address of the device nor scanning a QR code using a camera. The link should have the following format:
https://my.angelcam.com/connect/angelcam-ready-direct/{UUID}/
where {UUID} will be UUID of the particular Arrow client. You can get the UUID from the configuration files mentioned above.
Warning: DO NOT expose the configuration files via an HTTP server in your device!!! If you need to read the UUID from an HTTP endpoint, you can use the --identity-file option to create a file containing just the UUID and expose this file.
It is also possible to put a sticker with QR code containing this link directly on your device or on a box.
When selecting a stream for the Arrow client, pay attention to the video codec and overall bitrate of the stream. Angelcam currently supports h264 and MJPEG codecs. In order to avoid using the whole upload bandwidth of your customers' Internet connection, the bitrate should not be too high. A reasonable bitrate is around 1 Mbps.
When using h264, the GoP size should not exceed 6 seconds.
The client cannot run in multiple instances at the same time. You can use the --lock-file parameter to create a lock file that will prevent this.