Immix

Introduction

Giraffe have built an integration with Immix using the Generic RTSP & SMTP Integration

Features supported:

Live View
Alarms
Audio Talk down (via a phone call).

A really important step...

Whilst we would absolutely love to build a better integration with Immix, we have so far been unable to convince Immix to work with us :) We would be eternally grateful if you could drop your Immix sales rep an email asking them to considering integrating with us properly 🦒🦒

This would allow us to support native audio talk down, floodlight / strobe light control and automatic configuration.

General configuration

Immix device setup

Create a Site in Immix in the usual way.
Create a Device in Immix:
1. We suggest naming the device System XXXX where XXXX is the System ID from Giraffe.
2. The type must be 'Generic Stream'.

The IP/Host field can be set to rtsp.onvp.io. This is not strictly necessary but will help identify the device when running reports that rely on the host name. Unfortunately it is not possible to be any more granular than this due to limitations with Immix's generic integration that we rely on.
The Port must be set to blank or 0. The Username and Password fields must be left blank.
The RTSP & OptionNames must be set as:

rtsps://system-XXXX:[email protected]:322/camera/{#}/2

The XXXX must be replaced with the Giraffe System ID.

The YOUR_API_KEY must be replaced with either a system authentication token or a personal access token (PAT). The system authentication token can be found on the RTSP tab:

You can use either RTSP or RTSPS but we recommend using RTSPS because it is encrypted and much more secure. If you are using a PAT to authenticate you must use RTSPS. Ensure the port is correct (554 for insecure and 322 for secure).

We highly recommend using the SD streams rather than HD streams. The stream resolution can be configured by changing the final digit in the URL.

Digit

Resolution

Tertiary (typically thermal)

You can optionally tick Use Passthrough. This means the Immix server does not need to re-encode the video from the camera. The Giraffe platform already sends it in the correct format.

We recommend unticking 'Receive undefined alarms' and ticking 'Log disarmed alarms'. If you enabled receiving of undefined alarms you will get all alarms regardless of rules.

At this point you should be able to view a camera by typing the Giraffe assigned Camera ID into the preview box:

Then save the record. Do not add any cameras at this stage.

Immix camera setup

Add a new camera to the device. The camera must be added to the device that you just created.

The Input Number must be set to the Giraffe Camera ID.

We recommend naming the camera with the Giraffe Camera ID in the name (for example Back door [5417]).

The quality field has no effect. Unfortunately the Generic Integration method in Immix has no way of controlling the camera resolution other than hard coding it.

In order to receive the alarms from the Edge Controller in Immix, you must create a device on the site called 'Giraffe Edge Controller' and this must be setup as a 'Generic Stream Integration'. Any other type of device in Immix will not process the XML formatted emails.

Giraffe setup

In order to setup the Immix integration, you must select 'Immix' as the ARC integration type in Giraffe software for the relevent system.

The 'ARC Identity' field should be set the S number you have been given in Immix.

Be aware that Giraffe will automatically form the Immix 'S number' email address based on the site ID that you provide.

So if you provde '12345' as the ARC Identity field, we will convert it to [email protected]

The SMTP details should be matched to your Immix server ones. Please note the emails are sent by connecting to your server rather than via our mail servers.

Camera Setup

If the cameras are setup in the recommended way, there is no need to make any changes to the individual ARC configuration per camera on the Giraffe side.

The Camera ARC identity is what will be sent through to Immix as the Input ID (or camera ID) in the event emails. If the Camera ARC identity is left blank, we will send the unique Giraffe camera ID instead.

Alarm Setup

You will typically create alarms for each camera as below. The input ID should match the camera ID.

The camera alarm types can either be set to Default to catch everything, or match a specific alarm such as Person Detected. See the following section for available mappings.

For all other alarms such as Mains Failure or Power Down, you must set the input ID to -1 .

You can receive all alarms by creating an alarm for type Default with the input ID of -1.

You may want to filter out LogicalEvent alarms as these tend to be noisy.

You can easily test any individual event type by copying from the examples below and pasting them into the test email feature on the ARC configuration screen.

For instance, if you want to test a mains failure alarm, you would need to enter the following text into the test email field:

<Alarm>
    <VersionInfo>1</VersionInfo>
    <Input1></Input1>
    <EventType>Mains Failure</EventType>
    <ExtraText>Mains power disconnected</ExtraText>
    <DateTime>2023‐07‐26T11:00:00Z</DateTime>
    <Location></Location>
    <URL>https://app.onvp.io</URL>
</Alarm>

Audio talkdown

In order to use the audio talkdown, we recommend using our telephone method at the moment.

We suggest putting the phone number and site broadcast code in the 'Notes2' field on the site settings page.

This can then be viewed by the operator by clicking on the Details button on the alarm handling screen

You may wish to save the main phone number as a speed dial in your phone system. This number is constant - only the site code changes between systems.

Event mapping

Giraffe will send Immix emails in the following formats. We have tried to map our events to the Immix events as far as possible, but there is not always a perfect match.

In all of the following events, some variables will be replaced:

{{ timestamp }} => replaced with the timestamp that the event occurred at (note this is different to the timestamp the event was received at).

S Numbers

Emails are sent to Immix with the 'to' address set to the format "Sx@ImmixAlarms.com". The x is replaced with the ID entered into the 'ARC Identity' field on the ARC configuration screen.

The from address will always be set to [email protected] (the x is replaced with the Giraffe unique system ID).

Intrusion events

AI event

Where the event was generated by an object detection (person or vehicle), we will send the following event to Immix. We will also attach snapshot images if available.

<Alarm>
    <VersionInfo>1</VersionInfo>
    <Input1>{{ camera_id }}</Input1>
    <EventType>PersonDetected</EventType>
    <ExtraText>{{ camera_name }} Camera ID: {{ camera_id }} System ID: {{ system_id }}</ExtraText>
    <DateTime>{{ timestamp }}</DateTime>
    <Location></Location>
    <URL>https://app.onvp.io</URL>
</Alarm>

{{ camera_id }} => the ARC identity configured on the camera record, or the Giraffe camera ID if the ARC identity is blank. {{ camera_name }} => the camera's friendly name in the Giraffe platform. If the name is blank, it will be set to the camera's Giraffe ID.

If the object detected is a vehicle, the Event parameter will be set to VehicleDetected

Up to five snapshot images will be attached to the email sent to Immix. These images will be named with the timestamp they were each taken like in the following photo:

The Giraffe platform will wait for 30s after an initial event is received for the snapshots to be received. As soon as 5 snapshots are received, the Giraffe platform will immediately forward the event to Immix.

If the 5 snapshots have not been received within 30s, the Giraffe platform will forward the event to Immix anyway with whatever snapshots it has received. The Giraffe platform will not attempt to resend the snapshots if they are subsequently received later.

PIR sensor trigger

Where the event originated from a source that did not provide a snapshot (such as a PIR sensor) we will send the following event. The Input1 value will always be set to the PIR ID plus 100000000. For instance, PIR ID 3 will come through as 100000003.

<Alarm>
    <VersionInfo>1</VersionInfo>
    <Input1>10000000X</Input1>
    <EventType>InputAlarm</EventType>
    <ExtraText>PIR Sensor {{ pir_id }} triggered</ExtraText>
    <DateTime>{{ timestamp }}</DateTime>
    <Location></Location>
    <URL>https://app.onvp.io</URL>
</Alarm>

{{ pir_id }} will be replaced with the ID of the PIR sensor that triggered. This will typically be an integer between 0 and 3.

Where it is a wireless PIR sensor that has triggered, the event will be as follows.

The Input1 value will always be set to the PIR ID plus 100000100. For instance, PIR ID 3 will come through as 100000103.

<Alarm>
    <VersionInfo>1</VersionInfo>
    <Input1>10000000X</Input1>
    <EventType>InputAlarm</EventType>
    <ExtraText>Wireless PIR Sensor {{ pir_id }} triggered</ExtraText>
    <DateTime>{{ timestamp }}</DateTime>
    <Location></Location>
    <URL>https://app.onvp.io</URL>
</Alarm>

{{ pir_id }} will be replaced with a value between 0 and 63 for a wireless PIR sensor.

Other intrusion events

When an intrusion event other than those mentioned above is generated, it will be sent to Immix in the following format using Immix's 'LogicalEvent' event.

We do not set the Input1 parameter.

<Alarm>
    <VersionInfo>1</VersionInfo>
    <Input1></Input1>
    <EventType>LogicalEvent</EventType>
    <ExtraText>Module: {{ module }}, Action: {{ action }}, Metadata: {{ metadata }}</ExtraText>
    <DateTime>{{ timestamp }}</DateTime>
    <Location></Location>
    <URL>https://app.onvp.io</URL>
</Alarm>

{{ module }} => the module that triggered the event, eg. 'doors' {{ action }} => the action that triggered the event, eg. 'opened' {{ metadata }} => any additional information that was passed along with the event, eg. '{ "door_id": 4 }'

Tamper events

Tamper events are always sent to Immix using an empty Input1 code.

Mains power connected / disconnected

When the mains power is disconnected, we will send the following event to Immix.

<Alarm>
    <VersionInfo>1</VersionInfo>
    <Input1></Input1>
    <EventType>Mains Failure</EventType>
    <ExtraText>Mains power disconnected</ExtraText>
    <DateTime>{{ timestamp }}</DateTime>
    <Location></Location>
    <URL>https://app.onvp.io</URL>
</Alarm>

Note that 'Mains Failure' has a space in it, unlike most of the other events.

When the power is connected again, we will send an event like this. Unfortunately Immix does not have an event to indicate restoration of power loss so we send it as a SystemEvent which you can code to a lower priority alarm.

<Alarm>
    <VersionInfo>1</VersionInfo>
    <Input1></Input1>
    <EventType>Mains Failure</EventType>
    <ExtraText>Mains power connected</ExtraText>
    <DateTime>{{ timestamp }}</DateTime>
    <Location></Location>
    <URL>https://app.onvp.io</URL>
</Alarm>

Auxilliary power connected / disconnected

Similar to mains power, when auxilliary power is disconnected, we will send the following event. Immix does not have a specific event for auxiliary power.

<Alarm>
    <VersionInfo>1</VersionInfo>
    <Input1></Input1>
    <EventType>Mains Failure</EventType>
    <ExtraText>Auxilliary power disconnected</ExtraText>
    <DateTime>{{ timestamp }}</DateTime>
    <Location></Location>
    <URL>https://app.onvp.io</URL>
</Alarm>

And the restore message is similar, but sent as a SystemEvent again.

<Alarm>
    <VersionInfo>1</VersionInfo>
    <Input1></Input1>
    <EventType>SystemEvent</EventType>
    <ExtraText>Auxilliary power connected</ExtraText>
    <DateTime>{{ timestamp }}</DateTime>
    <Location></Location>
    <URL>https://app.onvp.io</URL>
</Alarm>

Doors opened / closed

When the doors are opened, we send a DoorForced event:

<Alarm>
    <VersionInfo>1</VersionInfo>
    <Input1></Input1>
    <EventType>DoorForced</EventType>
    <ExtraText>Doors opened</ExtraText>
    <DateTime>{{ timestamp }}</DateTime>
    <Location></Location>
    <URL>https://app.onvp.io</URL>
</Alarm>

When the doors are closed again, we have to send a SystemEvent event, with a descriptive message in ExtraText:

<Alarm>
    <VersionInfo>1</VersionInfo>
    <Input1></Input1>
    <EventType>DoorForced</EventType>
    <ExtraText>Doors closed</ExtraText>
    <DateTime>{{ timestamp }}</DateTime>
    <Location></Location>
    <URL>https://app.onvp.io</URL>
</Alarm>

Tilt sensor

When the tilt sensor is triggered, we send the following event (using the generic 'TamperAlarm' event:

<Alarm>
    <VersionInfo>1</VersionInfo>
    <Input1></Input1>
    <EventType>TamperAlarm</EventType>
    <ExtraText>Tilt sensor alarm</ExtraText>
    <DateTime>{{ timestamp }}</DateTime>
    <Location></Location>
    <URL>https://app.onvp.io</URL>
</Alarm>

And the following SystemEvent when the tilt sensor position returns to normal:

<Alarm>
    <VersionInfo>1</VersionInfo>
    <Input1></Input1>
    <EventType>TamperAlarm</EventType>
    <ExtraText>Tilt sensor normal</ExtraText>
    <DateTime>{{ timestamp }}</DateTime>
    <Location></Location>
    <URL>https://app.onvp.io</URL>
</Alarm>

Tamper sensor

The generic tamper sensor is almost identical to the tilt event:

<Alarm>
    <VersionInfo>1</VersionInfo>
    <Input1></Input1>
    <EventType>TamperAlarm</EventType>
    <ExtraText>Tamper sensor alarm</ExtraText>
    <DateTime>{{ timestamp }}</DateTime>
    <Location></Location>
    <URL>https://app.onvp.io</URL>
</Alarm>

As is the restore:

<Alarm>
    <VersionInfo>1</VersionInfo>
    <Input1></Input1>
    <EventType>TamperAlarm</EventType>
    <ExtraText>Tamper sensor normal</ExtraText>
    <DateTime>{{ timestamp }}</DateTime>
    <Location></Location>
    <URL>https://app.onvp.io</URL>
</Alarm>

Other tamper events

For any other tamper events that do not match the above, we send the following generic message:

We use the generic Immix 'LogicalEvent' event.

<Alarm>
    <VersionInfo>1</VersionInfo>
    <Input1></Input1>
    <EventType>LogicalEvent</EventType>
    <ExtraText>Module: {{ module }}, Action: {{ action }}, Metadata: {{ metadata }}</ExtraText>
    <DateTime>{{ timestamp }}</DateTime>
    <Location></Location>
    <URL>https://app.onvp.io</URL>
</Alarm>

System events

System events are always sent to Immix using an empty Input1 code.

Hard disk readable / unreadable

If there is a fault with the hard disk used by the recording system, we send the following event using the 'HDDFull' event

<Alarm>
    <VersionInfo>1</VersionInfo>
    <Input1></Input1>
    <EventType>HDDFull</EventType>
    <ExtraText>Hard disk ERROR. Reason: {{ reason }}</ExtraText>
    <DateTime>{{ timestamp }}</DateTime>
    <Location></Location>
    <URL>https://app.onvp.io</URL>
</Alarm>

{{ reason }} => can be either disk_missing or fsck_failed

Unfortunately Immix does not have a recording restored event, so we use the same HDDFull event with extra text.

<Alarm>
    <VersionInfo>1</VersionInfo>
    <Input1></Input1>
    <EventType>HDDFull</EventType>
    <ExtraText>Hard disk RECOVERY</ExtraText>
    <DateTime>{{ timestamp }}</DateTime>
    <Location></Location>
    <URL>https://app.onvp.io</URL>
</Alarm>

Battery time to go

When the system battery falls below a certain number of minutes remaining, the following event is sent. We have to use the SystemEvent event type because Immix does not have a low battery event.

<Alarm>
    <VersionInfo>1</VersionInfo>
    <Input1></Input1>
    <EventType>SystemEvent</EventType>
    <ExtraText>Battery LOW. Estimated time remaining: {{ time_remaining }} minutes. Voltage: {{ battery_voltage }}V. Remaining capacity: {{ percent_remaining }}%</ExtraText>
    <DateTime>{{ timestamp }}</DateTime>
    <Location></Location>
    <URL>https://app.onvp.io</URL>
</Alarm>

{{ time_remaining }} => the remaining time in minutes {{ battery_voltage }} => the battery voltage at the time of the alert {{ percent_remaining }} => a percentage indication of how much battery is left vs the overall capacity of the battery.

When the battery time remaining rises back above the threshold, the following event is sent (again using the 'SystemEvent' event because Immix does not have a battery restore event):

<Alarm>
    <VersionInfo>1</VersionInfo>
    <Input1></Input1>
    <EventType>SystemEvent</EventType>
    <ExtraText>Battery RECOVERY. Estimated time remaining: {{ time_remaining }} minutes. Voltage: {{ battery_voltage }}V. Remaining capacity: {{ percent_remaining }}%</ExtraText>
    <DateTime>{{ timestamp }}</DateTime>
    <Location></Location>
    <URL>https://app.onvp.io</URL>
</Alarm>

The threshold for the battery time to go alarm is configured in your device definition. Please contact Giraffe support if you wish to change it.

Status change (online / offline)

If the Giraffe platform notices the Edge Controller has gone offline, the following event will be generated using the 'DeviceShutdown' event. We have to use the DeviceShutdown event, because Immix does not have an 'offline' event that we can send.

<Alarm>
    <VersionInfo>1</VersionInfo>
    <Input1></Input1>
    <EventType>DeviceShutdown</EventType>
    <ExtraText>System is offline</ExtraText>
    <DateTime>{{ timestamp }}</DateTime>
    <Location></Location>
    <URL>https://app.onvp.io</URL>
</Alarm>

When the system comes online again, we use the 'DevicePowerup' event to signal it as online again

<Alarm>
    <VersionInfo>1</VersionInfo>
    <Input1></Input1>
    <EventType>DevicePowerup</EventType>
    <ExtraText>System is online</ExtraText>
    <DateTime>{{ timestamp }}</DateTime>
    <Location></Location>
    <URL>https://app.onvp.io</URL>
</Alarm>

Online / offline notifications may be delayed by a couple of minutes. This is to avoid 'nuisance' alerts that may be caused by temporary blips in internet connectivity.

Run switch on / off

When the Edge Controller is powered on / off using the switch (or when it is forced to shutdown due to low voltage), the following DeviceShutdown event will be sent:

<Alarm>
    <VersionInfo>1</VersionInfo>
    <Input1></Input1>
    <EventType>DeviceShutdown</EventType>
    <ExtraText>System switched off</ExtraText>
    <DateTime>{{ timestamp }}</DateTime>
    <Location></Location>
    <URL>https://app.onvp.io</URL>
</Alarm>

When the system is switched back on again, we send the following DevicePowerup event:

<Alarm>
    <VersionInfo>1</VersionInfo>
    <Input1></Input1>
    <EventType>DevicePowerup</EventType>
    <ExtraText>System switched on</ExtraText>
    <DateTime>{{ timestamp }}</DateTime>
    <Location></Location>
    <URL>https://app.onvp.io</URL>
</Alarm>

When the battery goes flat, you may experience a couple of off / on cycles in a row. This is because the battery has a tendency to 'bounce' a bit before going completely flat when the load is added / removed.

The DevicePowerup event will not always be sent. When the system is shutdown using the of / off switch (or by the Edge Controller low voltage cut off triggering), a DeviceShutdown alarm will always be sent.

However, the DevicePowerup event will only be sent if the on/off switch is returned to on prior to the shutdown happening (ie. within the 10 second delay period).

If the Edge Controller is powered on from cold, you will instead receive a status change to online event once the system has booted.

This is because we cannot monitor the status of the on/off switch, until the system has booted.

Other system events

For any other system events that do not match the above, we send the following generic message using the Immix 'LogicalEvent' event:

<Alarm>
    <VersionInfo>1</VersionInfo>
    <Input1></Input1>
    <EventType>LogicalEvent</EventType>
    <ExtraText>Module: {{ module }}, Action: {{ action }}, Metadata: {{ metadata }}</ExtraText>
    <DateTime>{{ timestamp }}</DateTime>
    <Location></Location>
    <URL>https://app.onvp.io</URL>
</Alarm>

Integrating multiple Edge Controllers

If you have multiple systems / Edge Controllers on a single site, you need to create an S number in Immix for each individual system / Edge Controller.

Firewall Whitelisting

Immix can be configured to reject emails coming from devices which it does not recognise.

If your Immix instance is configured in this way you will need to setup a dummy site called 'Giraffe' and create some dummy devices on this site that have the Giraffe server's IP address as their hostname. This will then whitelist the IP globally in your Immix instance.

The IP addresses can be found on the firewall whitelisting page.

PreviousGeneric integration NextSentinel - deprecated

Last updated 9 minutes ago