ICU Server Event Types

These are the two event types the ICU Server integration needs. Set up the integration itself first; this article covers only the event types it writes to.

Supported event types

EarthRanger event type Display title What it carries
cameratrap_rep Camera Trap One camera trap image and the AI detections found in it. The image is attached to the event after it is created.
camera_status_report Camera Status Report A periodic report on the camera itself — battery, signal, settings. No image.

Both events carry the camera's IMEI as the source and the camera's coordinates as the location. A camera with no known position reports 0.0 / 0.0.

Camera Trap fields

Field Label Type What it holds
cameratraprep_camera-name Camera Name Text The camera's name, e.g. North Gate.
cameratraprep_camera-make Camera Make Text Camera model title, e.g. M350GW.
detections Detections Sub-form, repeating One entry per AI detection in the image; empty when the image contains none. Each entry holds the fields below.
category Category Text What was detected, e.g. human or vehicle.
confidence_percent Confidence % Number How confident the detection is, 0–100, e.g. 96.2.
x_px, y_px, width_px, height_px Bounding Box X / Y / Width / Height (px) Number Where the detection sits in the image, in pixels — the top-left corner plus width and height, in COCO format.

The bounding box is reserved. ICU sends all four box values as 0 today. The fields exist so the boxes can be used once ICU starts sending them; until then they can be left off the form.

Camera Status Report fields

Every field is always sent. A field the camera has no value for arrives empty rather than being left out. The suggested form has three sections.

Device

Field Label Type What it holds
imei IMEI Text The camera's IMEI, e.g. 356938101234567.
iccid ICCID Text The SIM card's ICCID.
init_key Init Key Text The product init key.
camera_name Camera Name Text The camera's name, e.g. North Gate.
camera_model Camera Model Text Reserved — ICU sends this empty today.
firmware_version Firmware Version Text Firmware running on the camera, e.g. 1.4.2.
mobile_country_code Mobile Country Code Text MCC from the camera's last network report.
mobile_network_code Mobile Network Code Text MNC from the camera's last network report.
location_area_code Location Area Code Text LAC from the camera's last network report.
cell_id Cell ID Text Cell id from the camera's last network report.
customer_timezone Customer Timezone Text The camera's timezone, e.g. Africa/Nairobi.

Status

Field Label Type What it holds
battery_status Battery Status Number Battery level as a percentage, 0–100.
signal_strength Signal Strength Number Mobile signal strength. The scale depends on the camera model — some report 0–4, others 0–31.
temperature Temperature Number Temperature at the camera in degrees C; can be negative.
coordinate_switch Coordinate Switch Yes/No Whether the camera reports its coordinates.
work_period Work Period Yes/No Whether the camera only operates during the hours set below.

Capture settings

Field Label Type What it holds
image_format Image Format Text Image aspect ratio, F4_3 or F16_9.
image_night Night Mode Text Night mode setting: MIN, ALL or MAX.
work_start Work Start Text Time of day the camera starts working, e.g. 06:00.
work_end Work End Text Time of day it stops, e.g. 21:00.
thumbnail_size Thumbnail Size Text Thumbnail resolution, e.g. 720p. The options vary by camera model.
pir_interval PIR Interval Text Delay between motion-sensor triggers, in seconds or a model-specific setting name.
time_scan Time Scan Text Time-lapse interval, in seconds or a model-specific setting name.
camera_language Camera Language Text Language set on the camera, e.g. en.

Why the settings fields are text, not numbers or times. Cameras report these differently depending on the model — pir_interval may be a number of seconds on one camera and a named setting on another, and the work hours arrive as HH:MM text. Text accepts whatever the camera sends, so nothing is dropped.

How to create these event types

1. Install the command-line tool and sign in

You need a terminal with Python 3.11 or newer and pipx installed, and an EarthRanger account on the target site. 

pipx install earthranger-cli                         # install the tool; this gives you the 'er' command

er profile add sitename --server sitename --username you   # save the site as a profile ('sitename' is the site's subdomain, e.g. 'borana' for borana.pamdas.org)
export ER_PROFILE=sitename                                 # tell 'er' to use that profile in this terminal
er auth login                                              # asks for your EarthRanger password and signs you in

Important: the account you log in with must have permissions on the Event Category that will host these event types.

2. Save this spec as icuserver.yaml

The spec puts both types in Monitoring. Change the category block at the top to use a different one. 

category:
  value: monitoring
  display: Monitoring
event_types:
- value: cameratrap_rep
  display: Camera Trap
  layout:
    label: ''
    columns: 1
  fields:
  - key: cameratraprep_camera-name
    label: Camera Name
    type: string
  - key: cameratraprep_camera-make
    label: Camera Make
    type: string
  - key: detections
    label: Detections
    type: collection
    item_name: detection
    fields:
    - {key: category, label: Category, type: string}
    - {key: confidence_percent, label: Confidence %, type: number}
    - {key: x_px, label: Bounding Box X (px), type: integer}
    - {key: y_px, label: Bounding Box Y (px), type: integer}
    - {key: width_px, label: Bounding Box Width (px), type: integer}
    - {key: height_px, label: Bounding Box Height (px), type: integer}
- value: camera_status_report
  display: Camera Status Report
  geometry_type: point
  sections:
  - label: Device
    fields:
    - {key: imei, label: IMEI, type: string}
    - {key: iccid, label: ICCID, type: string}
    - {key: init_key, label: Init Key, type: string}
    - {key: camera_name, label: Camera Name, type: string}
    - {key: camera_model, label: Camera Model, type: string}
    - {key: firmware_version, label: Firmware Version, type: string}
    - {key: mobile_country_code, label: Mobile Country Code, type: string}
    - {key: mobile_network_code, label: Mobile Network Code, type: string}
    - {key: location_area_code, label: Location Area Code, type: string}
    - {key: cell_id, label: Cell ID, type: string}
    - {key: customer_timezone, label: Customer Timezone, type: string}
  - label: Status
    fields:
    - {key: battery_status, label: Battery Status, type: integer, min: 0, max: 100}
    - {key: signal_strength, label: Signal Strength, type: integer}
    - {key: temperature, label: Temperature, type: integer}
    - {key: coordinate_switch, label: Coordinate Switch, type: boolean}
    - {key: work_period, label: Work Period, type: boolean}
  - label: Capture Settings
    fields:
    - {key: image_format, label: Image Format, type: string}
    - {key: image_night, label: Night Mode, type: string}
    - {key: work_start, label: Work Start, type: string}
    - {key: work_end, label: Work End, type: string}
    - {key: thumbnail_size, label: Thumbnail Size, type: string}
    - {key: pir_interval, label: PIR Interval, type: string}
    - {key: time_scan, label: Time Scan, type: string}
    - {key: camera_language, label: Camera Language, type: string}

cameratrap_rep already exists on most EarthRanger sites. Applying this spec adds the fields to it and leaves the rest of the type alone. Icons are not set by the spec — pick them in EarthRanger under Activity → Event Types.

3. Preview, then apply

er events apply icuserver.yaml --dry-run   # shows what will be created or changed
er events apply icuserver.yaml             # actually does it

Applying is safe to repeat: it creates what is missing and patches only what differs. Nothing is ever deleted.

4. Verify

er events show event-type camera_status_report
er events show event-type cameratrap_rep

CLI tool and full spec documentation: https://github.com/PADAS/earthranger-cli