-
Notifications
You must be signed in to change notification settings - Fork 0
Arduino Tracker
HOME > [SNOWPLOW TECHNICAL DOCUMENTATION](SnowPlow technical documentation) > Trackers
-
- 2.1 Initialization
- 2.1.1 Required headers
- 2.1.2 Initialize SnowPlowTracker
- 2.2 Setting the endpoint
- 2.3 Setting the user ID
- 2.3.1
setUserId
- 2.3.1
- 2.1 Initialization
- 4 Testing and debugging
- 4.1 Setup debugging
The SnowPlow Arduino tracker allows you to track SnowPlow events from an IP-connected Arduino arduino board.
The tracker should be straightforward to use if you are familiar with Arduino development; any prior experience with SnowPlow's JavaScript tracker or Google Analytics (which has a similar API to SnowPlow) is helpful but not necessary.
Note that this tracker has access to a much more restricted set of SnowPlow events than other trackers.
## 2. General parameters ### 2.1 InitializationYou must add some initialization code to the top of your Arduino sketch, before your setup()
function:
Make sure you have the following includes:
#include <SPI.h>
#include <Ethernet.h>
#include <SnowPlowTracker.h>
After your includes but before your setup()
function, initialize your SnowPlowTracker
something like this:
// MAC address of this Arduino. Update with your shield's MAC address.
const byte mac[] = { 0x90, 0xA2, 0xDA, 0x00, 0xF8, 0xA0 };
// SnowPlow app name
const char *snowplowAppName = "my-arduino-project";
// SnowPlow Tracker
SnowPlowTracker snowplow(&Ethernet, mac, snowplowAppName);
Note that this initialization includes setting the application ID for your Arduino project, as well as your device's MAC address.
### 2.2 Setting the endpointEndpoint refers to the location of your collector: you need to point your Arduino tracker to your collector endpoint, to ensure that data generated by your Arduino is logged by the collector.
If you are using a Cloudfront collector you can use initCf to set the endpoint. If you are using any other collector (e.g. the Clojure collector, or SnowCannon), then you should use initUrl.
#### 2.2.1 Setting a Cloudfront endpoint using `initCf()`You can set the collector endpoint for the Cloudfront collector by adding to your setup()
function:
snowplow.initCf("{{CLOUDFRONT-SUBDOMAIN}}");
So if your Cloudfront subdomain is d3rkrsqld9gmqf
, you would include:
snowplow.initCf("d3rkrsqld9gmqf");
This completes the initialization of your SnowPlowTracker
.
If you are running a different collector (not the Cloudfront collector) then add to your setup()
function:
snowplow.initUrl("{{COLLECTOR-URL}}");
So if your collector endpoint is at 'my-company.c.snplow.com' then you would include:
snowplow.initUrl("my-company.c.snplow.com");
This completes the initialization of your SnowPlowTracker
.
The Arduino Tracker automatically passes to the collector the mac_address
supplied on initialization.
However you may want to identify a specific Arduino board by a more business-friendly name. To do this, you use the setUserId
method.
To set a business-friendly user ID for this Arduino, use the setUserId()
method i.e.:
snowplow.setUserId("boardroom-arduino");
SnowPlow has been built to enable you to track a wide range of events that occur when users interact with your websites and apps. We are constantly growing the range of functions available in order to capture that data more richly.
All tracking functions at a glance:
Function | Description |
---|---|
trackStructEvent |
Track a SnowPlow custom structured event |
All events are tracked with specific Arduino C++ functions of the form trackXXX
, where XXX
is the name of the event to track.
A given event type may have multiple different signatures (to support slightly different argument options or types).
### 3.1.1 Return codesAll trackXXX
functions return an integer to report the status of the attempt to track the given event object.
The full list of return codes are given below:
Constant | Integer value | Description |
---|---|---|
ERROR_CONNECTION_FAILED |
-1 | Could not connect to SnowPlow collector |
ERROR_TIMED_OUT |
-2 | SnowPlow collector did not respond |
ERROR_INVALID_RESPONSE |
-3 | SnowPlow collector's response couldn't be parsed |
ERROR_MISSING_ARGUMENT |
-4 | Required argument(s) to trackXXX missing |
ERROR_HTTP_STATUS |
-5 | HTTP status code returned by SnowPlow collector was server or client error |
N/A | 1-399 | Non-error HTTP status code returned by SnowPlow collector |
You can access these constants in your code by prepending with SnowPlowTracker::
, for example:
int ret_val = snowplow.trackXXX;
if (ret_val == SnowPlowTracker::ERROR_HTTP_STATUS) {
...
}
Custom structured events are the only form of tracking currently supported by the SnowPlow Arduino tracker. Whenever you want to record an event or sensor reading from your IP-connected Arduino, use trackStructEvent
to send this data to SnowPlow.
Some examples of tracking custom structured events from your Arduino board(s) might include:
- Monitoring the environment (temperature, humidity, light levels etc) in your warehouse/factory/workplace/shop/museum
- Tracking the movement of products around your shop/warehouse/factory using Arduino, [RFID readers] arduino-rfid and SnowPlow
- Sending vehicle fleet information (locations, speeds, fuel levels etc) back to SnowPlow using Arduino's [3G and GPS] 3g-gps shields
There are five arguments associated with each structured event. Of them, only the first two are required:
Name | Required? | Description |
---|---|---|
aCategory |
Yes | The name you supply for the group of objects you want to track e.g. 'sensor', 'ecomm' |
aAction |
Yes | A string which defines the type of user interaction for the web object e.g. 'read-temp', 'wifi-strength' |
aLabel |
No | An optional string which identifies the specific object being actioned e.g. ID of the sensor being read |
aProperty |
No | An optional string describing the object or the action performed on it. This might be whether the temperature reading is in Fahrenheit or Celsius |
aValue |
No | An optional float or double to quantify or further describe the user action. This might be the price of an item added-to-basket, or the starting time of the video where play was just pressed |
There are four slightly different signatures for the tractStructEvent
, depending on what type of aValue
you want to supply:
The relevant signature for trackStructEvent
if you have no aValue
to log is:
int trackStructEvent(const char *aCategory,
const char *aAction,
const char *aLabel = NULL,
const char *aProperty = NULL) const;
Note that this version defaults aLabel
and aProperty
to NULL
if you don't set them. Here's an example invocation:
snowplow.trackStructEvent("example", "basic ping");
See Tracking return codes above for the return codes supported by trackStructEvent
.
The relevant signature for trackStructEvent
if aValue
is an integer is:
int trackStructEvent(const char *aCategory,
const char *aAction,
const char *aLabel,
const char *aProperty,
const int aValue) const;
Notes:
- Because
aValue
must be a float or double, this version oftrackStructEvent
appends ".0" to the end of the int before sending to SnowPlow - If you don't want to set
aLabel
oraProperty
, pass inNULL
in their place
Here's an example invocation:
snowplow.trackStructEvent("example", "profile-update", "age", NULL, 22);
See Tracking return codes above for the return codes supported by trackStructEvent
.
The relevant signature for trackStructEvent
to track a double in aValue
is:
int trackStructEvent(const char *aCategory,
const char *aAction,
const char *aLabel,
const char *aProperty,
const double aValue,
const int aValuePrecision = 2) const;
aValuePrecision
lets you specify the number of decimal places to use when logging the double aValue
(it defaults to two decimal places). Note that the default type for floating point literals in Arduino is double, not float.
Here's an example invocation:
snowplow.trackStructEvent("example", "constant", NULL, "pi", 3.14159, 5);
See Tracking return codes above for the return codes supported by trackStructEvent
.
The relevant signature for trackStructEvent
to track a float in aValue
is:
int trackStructEvent(const char *aCategory,
const char *aAction,
const char *aLabel,
const char *aProperty,
const float aValue,
const int aValuePrecision = 2) const;
aValuePrecision
lets you specify the number of decimal places to use when logging the float aValue
(it defaults to two decimal places). Note that the default type for floating point literals in Arduino is double, not float.
Here's an example invocation:
snowplow.trackStructEvent("example", "temp reading", NULL, "celsius", 15.3f, 1);
See Tracking return codes above for the return codes supported by trackStructEvent
.
This feature is on the roadmap: it has not been developed yet.
### 4 Testing and debuggingArduino is a difficult platform to test and debug software on, so it's important to understand what options the SnowPlow Arduino Tracker has for debugging.
#### 4.1 Setup debuggingBy default, debug logging to your Arduino Serial Monitor console is switched on for the SnowPlow Arduino Tracker, which should help you to identify any problems debugging your SnowPlow event tracking.
To switch off this logging when you are finished testing, edit this line found near the top of your copy of SnowPlowTracker.cpp
:
#define LOG_LEVEL 0x03 // Change to 0x00 when you've finished testing
As the comment says, change "0x03" to "0x00" to switch off all logging to your Arduino Serial Monitor console.
The full set of logging levels are as follows:
Constant | Integer value | Description |
---|---|---|
NO_LOG |
0x00 | Don't print any messages to the Serial Monitor console |
ERROR_LEVEL |
0x01 | Only print errors to the console |
INFO_LEVEL |
0x02 | Print errors and important messages to the console |
DEBUG_LEVEL |
0x03 | Print all errors and messages to the console |
Home | About | Project | Setup Guide | Technical Docs | Copyright © 2012-2013 Snowplow Analytics Ltd
HOME > [TECHNICAL DOCUMENTATION](Snowplow technical documentation)
1. Trackers
Overview
Javascript Tracker
No-JS Tracker
Lua Tracker
Arduino Tracker
2. Collectors
Overview
Cloudfront collector
Clojure collector (Elastic Beanstalk)
SnowCannon (node.js)
3. Enrich
Overview
EmrEtlRunner
Scalding-based Enrichment Process
C. Canonical Snowplow event model
4. Storage
Overview
[Storage in S3](S3 storage)
Storage in Redshift
Storage in PostgreSQL
Storage in Infobright (deprecated)
The StorageLoader
D. Snowplow storage formats (to write)
5. Analytics
Analytics documentation
Common
Artifact repositories