If you use the protegear platform, you have at least one device which sends data to our system. We call every record an Event and you can use eventhandlers to process these events.

What is an Eventhandler?

Every time such an event is received, the system looks for an eventhandler which is configured to handle this event. If no eventhandler is found, nothing happens; if more than one handler is found, all of them are executed in parallel.

A handler triggers some external action, for example:

• send an email
• send a short message (SMS)
• send a message to a chat (telegram)
• send a message to a slack channel
• send a message to a webhook

In all of this cases you can define the specifics of the channel and customize the message to be sent.

Let's develop a simple eventhandler which sends an email to a specific address, when the user of the device is sending a PRESET1 eventcode.

Please note that you can also write a handler which works for a SOS code, but be aware of rescue teams which are also triggered by an SOS.

Create the handler

In your protegear console, got the the Eventhandlers section and click on the Plus icon in the lower right corner. You will see a form to create a new eventhandler.

Here we give the handler the name "a simple email" and set the eventcode to PRESET1. Now click on the Save button in the upper right corner to create the handler (when the handler is new, the button will appear as a plus icon).

Now enter the recipient and body message and also select the device for which you want this handler to be executed.

To make sure that everything is ok, you can click on the Send test message button. The protegear platform will send you a test email to the address you have entered in the Recipient field.

If everything is ok, you will receive an email when one of your assigned devices sends the PRESET1 eventcode.

Dynamic data

Well, it looks pretty cool, but the email is always the same. Let's add some dynamic data to the email.

Change the subject

The subject should contain the device name, so you can assign this handler to multiple devices and still get the name of the device in the subject.

The protegear platform uses Go Templates to render the dynamic data. But to use this feature you need to know the available variables and how to use them. You can click the small question mark icon next to the Email content label which opens a new browser with the documentation of the variables and their layout.

In this post we will use this information to create the subject. One of the toplevel variables in the template is a Device which contains all information about the device which sent the event. So we can use the .Device.Name variable to get the name.

The syntax of go templates uses double curly braces to reference this value, so the subject will look like this:

{{.Device.Name}} sent a signal

Well, the name of a device is an optional field. So if you did not set the name of a device, this value will render as an empty string. To make sure, we still get some useful information, we will add the ID of the device too:

{{.Device.Name}} ({{.Device.ID}}) sent a signal

Now the subject contains the name and also the ID (the IMEI) of the device. So if your device does not have a name or you have multiple devices with the same name, you will still get the ID of the device in the subject to identify it.

Some body information

The body is also very poor. Let's add some more information about the device so at least we should know where the device is located.

When looking at the information of the variables, we also get a variable called Event which contains many information about the data the device sent. One of the fields of the event is the Position which itself contains a latitude and a longitude.

To embed the location, we can use the Position variable and render the Latitude and Longitude fields:

The user sent PRESET1.

Position: {{.Event.Position.Latitude}},{{.Event.Position.Longitude}}

But here is a little problem. The data type description shows, that the Position variable is a pointer to PositionInfo struct. So we need to check if this pointer is not nil before we access the fields. You might think that the device should always send a position, but this is not the case. There are situations where a device sends a signal although it does not have a valid position information. In this case this field will be nil. To make sure, our template does not crash, we need to check if the pointer is not nil before we access the fields.

The user sent PRESET1.

{{ with .Event.Position }}
Lat: {{.Latitude}}<br/>
Lng: {{.Longitude}}<br/>
{{ end }}

The with statement in a go template checks the given variable and only executes the block if it is not nil. So now we are sure, that the template with the position information will not crash if the device does not send it.

Now the body looks good, but there is one more thing. The eventcode is also a field inside the Event struct. So let's add this to the body too.

The user sent {{.Event.Code}}

<hr size="1"/>

{{ with .Event.Position }}
Lat: {{.Latitude}}<br/>
Lng: {{.Longitude}}<br/>
{{ end }}

If you now press your device button which sends the PRESET1 eventcode, you will receive an email with the subject and body containing the dynamic data

As you can see, the eventcode is rendered as CUSTOM1 as this is the name in the protegear platform for the PRESET1

Eye candy

As emails are sent as HTML, you can use some sugar to make them look fancy. Lets use an icon in the subject so the receiver will see a eventcode specific icon:

{{.Device.Name}} ({{.Device.ID}}) sent a signal: {{ icon .Event.Code }}

This will render the icon for the eventcode in the subject. The icon function is a built-in function of the protegear platform.

If you use a device which sends eventcodes for POWER-ON and POWER-OFF (like the A*Live) and you attach this eventcodes, you will get these notification emails:

More data

As the documetation shows, there are more fields in the template which can be used:

• Information
  Contains the information you stored in your protegear console preferences. You can store some medical information which you can embed in the email.
• Contacts
  The list of contacts you have stored in your protegear console. The list is unordered.
• Event
  The data the device sent to the platform which triggered the handler.
• Device
  The device itself which sent the event.

Other handler types

This example was built with a simple email handler, because most people can receive emails. But there are other handler types, which can be used to send data to other systems.

• SMS
  Send an SMS to a phone number.
• Telegram
  Send a message to a telegram channel.
• Slack
  Send a message to a slack channel.
• Webhook
  Send a HTTP POST request to a webhook URL.

A Webhook is the only handler which can be used for regular POSITION events from devices. As devices can have very small intervalls, you can use the webhook handler to send the data to a server which can process it. We do not allow this for the other handler types, because of rate limits of the receiving systems.

Conclusion

You can use handlers to process events sent by the devices. Depending on the eventcodes you can create different handlers which send data to different targets like emails, SMS, telegram or webhooks. The handlers can be configured to use different templates.

This is a powerful feature to notify people about different circumstances. But if you want real security, you should check our SmartSafety product. It is built on top of the protegear platform and does much more than just reacting to single events. It can check geofences, detect deadman or motionless situations, has multilevel alarming and much more. If you are interested, please contact us via the contact form on our website.