From 0be22243ff676e4fbb07dab3f3a49fe61545b1f4 Mon Sep 17 00:00:00 2001 From: Jan-Piet Mens Date: Tue, 30 Jul 2024 19:10:38 +0200 Subject: [PATCH] remove mentions of Greenwich devices --- doc/DESIGN.md | 2 +- doc/HOOKS.md | 2 +- doc/STORE.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/DESIGN.md b/doc/DESIGN.md index 75392b9..c77005e 100644 --- a/doc/DESIGN.md +++ b/doc/DESIGN.md @@ -3,7 +3,7 @@ We took a number of decisions when designing the Recorder and its utilities: * Flat files. The filesystem is the database. Period. That's were everything is stored. It makes incremental backups, purging old data, manipulation via the Unix toolset easy. (Admittedly, for fast geo-lookups we employ LMDB as a cache, but the final word is in the filesystem.) We considered all manner of databases and decided to keep this as simple and lightweight as possible. You can however have the Recorder send data to a database of your choosing, in addition to the file system it uses, by utilizing our embedded Lua hook. -* We wanted to store received data in the format it's published in. As this format is JSON, we store this raw payload in the `.rec` files. If we add an attribute to the JSON published by our apps, you have it right there. There's one slight exception: the monthly logs (the `.rec` files) have a leading timestamp and a relative topic; see below. (In the particular case of the OwnTracks firmware for Greenwich devices which can publish in CSV mode, we convert the CSV into OwnTracks JSON for storage.) +* We wanted to store received data in the format it's published in. As this format is JSON, we store this raw payload in the `.rec` files. If we add an attribute to the JSON published by our apps, you have it right there. There's one slight exception: the monthly logs (the `.rec` files) have a leading timestamp and a relative topic; see below. * File names are lower case. A user called `JaNe` with a device named `myPHONe` will be found in a file named `jane/myphone`. * All times are UTC (a.k.a. Zulu or GMT). We got sick and tired of converting stuff back and forth. It is up to the consumer of the data to convert to local time if need be. * The Recorder does not really provide authentication or authorization. Well, it does a bit. Think about this before making it available on a publicly-accessible IP address. Or rather: don't think about it; just don't do it. You can of course place a HTTP proxy in front of the Recorder to control access to it. Or use views (see below). diff --git a/doc/HOOKS.md b/doc/HOOKS.md index d8a59d5..035c8f9 100644 --- a/doc/HOOKS.md +++ b/doc/HOOKS.md @@ -79,7 +79,7 @@ It is 14:10:01 in the year 2015 owntracks/jane/phone lat=48.858339 Avenue Anatol An optional function you provide is called `otr_putrec(u, d, s)`. If it exists, it is called with the current user in `u`, the device in `d` and the payload -(which for OwnTracks apps is JSON but for, eg Greenwich devices might not be) in the string `s`. If your function returns a +(which for OwnTracks apps is JSON) in the string `s`. If your function returns a non-zero value, the Recorder will *not* write the REC file for this publish, will *not* update the `last` record, and will *not* forward the publish over the websocket (if used). ## `otr_httpobject` diff --git a/doc/STORE.md b/doc/STORE.md index dc4e9a0..2556303 100644 --- a/doc/STORE.md +++ b/doc/STORE.md @@ -5,7 +5,7 @@ As mentioned earlier, data is stored in files, and these files are relative to ` * `cards/`, optional, may contains user cards. This card is then stored here and used with, e.g., `ocat --last` to show a user's name and optional avatar. User cards are typically stored in a subdirectory called `username`, and therein a JSON file `[username].json`. When reading cards, the Recorder will first attempt to open `[username]/[device]/[username].json` and then `[username]/[username].json`. * `config/`, optional, contains the JSON of a [device configuration](http://owntracks.org/booklet/features/remoteconfig/) (`.otrc`) which was requested remotely via a [dump command](http://owntracks.org/booklet/tech/json/#_typecmd). Note that this will contain sensitive data. You can use this `.otrc` file to restore the OwnTracks configuration on your device by copying to the device and opening it in OwnTracks. * `ghash/`, unless disabled, reverse Geo data (using a Google service) is collected into an LMDB database located in this directory. This LMDB database also contains named databases which are used by your optional Lua hooks, as well as a `topic2tid` database which can be used for TID re-mapping. -* `last/` contains the last location published by devices. E.g. Jane's last publish from her iPhone would be in `last/jjolie/iphone/jjolie-iphone.json`. The JSON payload contained therein is enhanced with the fields `user`, `device`, `topic`, and `ghash`. If a device's `last/` directory contains a file called `extra.json` (i.e. matching the example, this would be `last/jjolie/iphone/extra.json`), the content of this file is merged into the existing JSON for this user and returned by the API. Note, that you cannot overwrite existing values. So, an `extra.json` containing `{ "tst" : 11 }` will do nothing because the `tst` element we obtain from location data overrules, but adding `{ "beverage" : "water" }` will do what you want. If Recorder is built with support for our Greenwich firmware, this directory might contain `batt.json`, `ext.json`, and/or `status.json` each of which hold an array of the last 100 reports for internal battery voltage, external voltage, and status respectively. These values are returned via the API in the LAST object. A file `http.json` which should contain either a single JSON object or an array of JSON objects is returned to clients in HTTP mode. +* `last/` contains the last location published by devices. E.g. Jane's last publish from her iPhone would be in `last/jjolie/iphone/jjolie-iphone.json`. The JSON payload contained therein is enhanced with the fields `user`, `device`, `topic`, and `ghash`. If a device's `last/` directory contains a file called `extra.json` (i.e. matching the example, this would be `last/jjolie/iphone/extra.json`), the content of this file is merged into the existing JSON for this user and returned by the API. Note, that you cannot overwrite existing values. So, an `extra.json` containing `{ "tst" : 11 }` will do nothing because the `tst` element we obtain from location data overrules, but adding `{ "beverage" : "water" }` will do what you want. These values are returned via the API in the LAST object. A file `http.json` which should contain either a single JSON object or an array of JSON objects is returned to clients in HTTP mode. * `monitor` a file which contains a timestamp and the last received topic (see Monitoring below). * `msg/` contains messages received by the Messaging system. * `photos/` optional; contains the binary photos from a card.