Immix

General configuration

Giraffe setup

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

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 [e-mail]

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.

Immix site setup

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.

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 please contact us for guidance. 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.

Camera Setup

It is important to setup the 'Camera ARC identity' on the 'Advanced' tab of the camera settings page.

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.

Integrating multiple Edge Controllers

If you have multiple Edge Controllers on a single site, there are two ways that you can configure the integration:

• by setting up each Edge Controller as an individual S numbers in Immix

• by setting up a single S number in Immix for the entire site, and configuring multiple Edge Controllers with identical settings.

In the second option above, it is important to give each camera a unique Camera ARC identity in order to differentiate the cameras in Immix.

If multiple Edge Controllers are configured using the same S number in Immix, you can differentiate between tamper and system alarms from the Edge Controllers using the Edge Controller system ID sent with each alarm.

Testing

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>9001</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>

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 "[e-mail]". 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 [e-mail] (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>AI event on camera: {{ camera_name }}</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 9002 for a PIR triggered event.

<Alarm>
    <VersionInfo>1</VersionInfo>
    <Input1>9002</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. We always set the Input1 value to 9003 for a wireless PIR event.

<Alarm>
    <VersionInfo>1</VersionInfo>
    <Input1>9003</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 'InputAlarm' event.

We always set the Input1 value to 9003 for all other types of intrusion event.

<Alarm>
    <VersionInfo>1</VersionInfo>
    <Input1>9004</Input1>
    <EventType>InputAlarm</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 a Input1 code of 9001.

Mains power connected / disconnected

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

<Alarm>
    <VersionInfo>1</VersionInfo>
    <Input1>9001</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>9001</Input1>
    <EventType>SystemEvent</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>9001</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>9001</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>9001</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>9001</Input1>
    <EventType>SystemEvent</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>9001</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>9001</Input1>
    <EventType>SystemEvent</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>9001</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>9001</Input1>
    <EventType>SystemEvent</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 'Tamper' event.

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

<EventType>HDDFull</EventType>
        <ExtraText>Hard disk unreadable. Reason: {{ $details['deviceEvent']['metadata']['reason'] }}</ExtraText>

{{ 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 }'

System events

System events are always sent to Immix using a Input1 code of 9000.

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>9000</Input1>
    <EventType>HDDFull</EventType>
    <ExtraText>Hard disk unreadable. 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 a SystemEvent

<Alarm>
    <VersionInfo>1</VersionInfo>
    <Input1>9000</Input1>
    <EventType>SystemEvent</EventType>
    <ExtraText>Hard disk readable</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 PanicAlarm event type because Immix does not have a low battery event.

<Alarm>
    <VersionInfo>1</VersionInfo>
    <Input1>9000</Input1>
    <EventType>PanicAlarm</EventType>
    <ExtraText>Battery warning. 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>9000</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 'PanicAlarm' event. We have to use the PanicAlarm event, because Immix does not have an 'offline' event that we can send.

<Alarm>
    <VersionInfo>1</VersionInfo>
    <Input1>9000</Input1>
    <EventType>PanicAlarm</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 'SystemEvent' event to signal it as online again

<Alarm>
    <VersionInfo>1</VersionInfo>
    <Input1>9000</Input1>
    <EventType>SystemEvent</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>9000</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>9000</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 'TamperAlarm' event:

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

<EventType>HDDFull</EventType>
        <ExtraText>Hard disk unreadable. Reason: {{ $details['deviceEvent']['metadata']['reason'] }}</ExtraText>

{{ 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 }'