How does time work in DevicePilot

Timezones are hard! Let's try to make them as straightforward as possible

Timezones are just a bit complicated to understand sometimes. Hopefully, DevicePilot has just worked as you expected, and you don't need to get into the details, but in case you do, here's how it works under the hood.

Time on ingesting data

All the data we take in is assumed to be "timezone aware" - that is, it's either in epoch time (always UTC) or its an ISO 8601 which defines it own time zone. Either way, we always store all data in UTC, to an accuracy no greater than milliseconds (technically ISO 8601 can be as accurate as microseconds, but we don't store at that resolution).

Out of order data

DevicePilot supports the data arriving out of order - but with some limits. The use case we've designed for is the idea of a offline device "catching up". If a device's comms go offline for a few hours, it might be designed to store its measurements during that period and then catch up when it comes back online. This case works well - we do request that you send the data in time order, oldest first. You just need to ensure the $ts value is set to the time that the measurement was taken.

It is possible to set data back to arbitrary times earlier, but we expect this to be rare and the system is not optimised for it. It could take several hours for a historical post to ripple through the system. If you think you want to send a significant amount of historical data, please contact support so we can help you do this efficiently. You may find that you get rate limited if you do persistent posting of data out of time order.

Time during querying data

Most of the time, querying data can just be done in UTC time, but when you want to say group data by day, you generally want the days to be midnight to midnight in the local time of the device. DevicePilot resolves this in two ways - a simple way and a more complicated one.

The simple way is that we assume the client is in the same timezone as the devices, and we pass the client timezone to the query so that it calculates the time bins correctly. This method is always used when using absolute time ranges, i.e. 3 hours, 1 day.

The more complicated way is required is the device estate spans multiple time zones. In this case, you can set the device's specific timezone by setting the timezone property using the IANA time zone database name (i.e. "Europe/Amsterdam"). This method is used when you use relative time ranges (i.e. Hour in day and day in week) to ensure that you can use this kind of relative analysis across time zones. For instance, if you have thermostats deployed around the world, and you wanted to analyse the activity on them by time of day, you'd want to aggregate all the local 9am time bins together, regardless of time zone.

Time during displaying data

The DevicePilot web application always displays data in the browser's local timezone, converting from the UTC that we store in. Most browsers just take their time zone from the operating system setting. As discussed above, the browser time zone is also used for all querying and display, so that, for instance, grouping by day is always whole, real days rather than arbitrary 24 hour periods.