diff --git a/docs/development/api.md b/docs/development/api.md index dff15b5dd..5352ff5bf 100644 --- a/docs/development/api.md +++ b/docs/development/api.md @@ -107,8 +107,8 @@ This should be used to replace `[AUTH]` in the `curl` examples that follow. farmOS provides an informational API endpoint at `/farm.json`, which includes the farm name, URL, API version, the system of measurement used by the farm, -information about the currently authenticated user, and information about -available entity types and bundles. +information about the currently authenticated user, installed languages, and +information about available entity types and bundles. For example: @@ -121,6 +121,15 @@ For example: "uid": "3", "name": "My Username", "mail": "myemail@mydomain.com", + "language": "en", + }, + "languages": { + "en": { + "language": "en", + "name": "English", + "native": "English", + "direction": 0, + }, }, "resources": { "log": { @@ -150,6 +159,8 @@ and a list of available `fields` and their metadata (`label`, `required`, etc). The `taxonomy_term` bundles also contain their `vid` (vocabulary ID), which is necessary when creating new terms (see [Creating taxonomy terms]). +Other modules can add information to `/farm.json` with `hook_farm_info()`. + ### API Version **Current API version: 1.3** diff --git a/docs/guide/areas.md b/docs/guide/areas.md index dec089777..ed5684cfd 100644 --- a/docs/guide/areas.md +++ b/docs/guide/areas.md @@ -189,6 +189,31 @@ Beds will be numbered and labeled using the parent area's name. +## Use the Snapping Grid + +FarmOS includes a "snapping grid" tool to aid in creating regular/aligned +geometries. By default when drawing, the cursor will only snap to existing +areas. However, the snapping grid adds a grid of evenly spaced points to which +the cursor will snap preferentially. + +![snapping_grid_demo](https://user-images.githubusercontent.com/30754460/88995756-5cb22300-d2a0-11ea-88a1-50edac1c0168.gif) + +To activate the grid, click the '#' icon in the bottom left corner above the +scale line, then select two points. The first point is the "origin" of the grid +while the second point we will call a "rotation anchor" and describes how the +grid should be rotated around the origin point. + +In addition to controlling the origin/rotation of the grid, its dimensions can +be specified. To do so, hovor your mouse over the '#' icon then enter the `x` and +`y` dimensions in the controls which appear.Since the grid can be rotated the +dimensions are independent of the compass directions on the map. Instead, the `x` +dimension represents the distances between the grid points on lines parallel with +the line formed by the origin and rotation anchor points. Similarly, the `y` dimension +represents distances perpendicular to that line. + +![farmOS Snapping Grid dimensions screenshot](/img/snapping_grid_dimension_explanation.png) + + [logging events]: /guide/logs [setting location of assets]: /guide/location [Google Earth]: https://www.google.com/earth diff --git a/docs/guide/assets/sensors.md b/docs/guide/assets/sensors.md index 36aca7b41..6d92e564c 100644 --- a/docs/guide/assets/sensors.md +++ b/docs/guide/assets/sensors.md @@ -91,11 +91,46 @@ include: * `start`: Filter data to timestamps greater than or equal to this start timestamp. * `end`: Filter data to timestamps less than or equal to this end timestamp. -* `limit`: The number of results to return. +* `limit`: The number of results to return. See "Limits" below for details. * `offset`: The value to start at. **Example filtered by name:** `https://myfarm.farmos.net/farm/sensor/listener/xxxxxx?private_key=yyyyyy&name=temperature` +**Limits** + +The `limit` parameter can be used to specify how many data points should be +returned. Setting `limit` to `0` will return the maximum number of points, which +is capped at `100000` (to prevent memory exhaustion). If more data is desired, +multiple requests should be made using the `offset` parameter. Setting `limit` +to a value greater than the max will result in a response code of +`422 Unprocessable Entity: exceeds max limit of 100000`. + +**Data summary info** + +It's also possible to retrieve summary information about the data stored for a +particular sensor by adding `/summary` to the end of the sensor's URL. This will +list each unique `name` used in the data, along with the total `count` of values +and the `first` and `last` timestamp for each. For example: + +`https://myfarm.farmos.net/farm/sensor/listener/xxxxxx/summary?private_key=yyyyyy` + +Example JSON response: + +``` +{ + "humid": { + "count": 100, + "first": "1541117473", + "last": "1594911898" + }, + "temp": { + "count": 100, + "first":"1541117473", + "last":"1594911898" + } +} +``` + **Allowing public API read access** Data in farmOS is private by default. A private key is required to push data to diff --git a/docs/img/snapping_grid_dimension_explanation.png b/docs/img/snapping_grid_dimension_explanation.png new file mode 100644 index 000000000..70852433e Binary files /dev/null and b/docs/img/snapping_grid_dimension_explanation.png differ diff --git a/docs/img/snapping_grid_dimension_explanation.svg b/docs/img/snapping_grid_dimension_explanation.svg new file mode 100644 index 000000000..911cd0a86 --- /dev/null +++ b/docs/img/snapping_grid_dimension_explanation.svg @@ -0,0 +1,497 @@ + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + Origin + Rotation Anchor + + + + + X + Y + + + +