feature: Weather API definition.

docs/src/SUMMARY.md

@@ -15,7 +15,9 @@
 # Feature How Tos
   * [Anchor Alarm](./features/anchoralarm/anchoralarm.md)
   * [NMEA0183 Server](./features/navdataserver/navdataserver.md)
+  * [Working with Weather Data](./features/weather/weather.md)
   * [Data Logging](./features/datalogging/datalogging.md)
+
 # Support
 * [Help & Support](./support/help.md)
   * [FAQs](./support/faq.md)
@@ -31,6 +33,7 @@
   * [Resource Providers](./develop/plugins/resource_provider_plugins.md)
   * [Course Providers](./develop/rest-api/course_calculations.md)
   * [Autopilot Providers](./develop/plugins/autopilot_provider_plugins.md)
+  * [Weather Providers](./develop/plugins/weather_provider_plugins.md)
 * [Publishing to the AppStore](./develop/plugins/publishing.md)
 * [REST APIs](./develop/rest-api/open_api.md)
   * [Course API](./develop/rest-api/course_api.md)
@@ -39,5 +42,6 @@
   * [Notifications API](./develop/rest-api/notifications_api.md)
   * [Autopilot API](./develop/rest-api/autopilot_api.md)
   * [Anchor API](./develop/rest-api/anchor_api.md)
+  * [Weather API](./develop/rest-api/weather_api.md)
 * [Contribute](./develop/contributing.md)
 

docs/src/develop/plugins/resource_provider_plugins.md

@@ -81,7 +81,7 @@ _**Note: The Resource Provider is responsible for implementing the methods and r
 
 _Note: It is the responsibility of the resource provider plugin to filter the resources returned as per the supplied query parameters._
 
-- `query:` Object contining `key | value` pairs repesenting the parameters by which to filter the returned entries. _e.g. {region: 'fishing_zone'}_
+- `query:` Object containing `key | value` pairs repesenting the parameters by which to filter the returned entries. _e.g. {region: 'fishing_zone'}_
 
 returns: `Promise<{[id: string]: any}>`
 

docs/src/develop/plugins/server_plugin_api.md

@@ -652,6 +652,99 @@ in the specified direction and starting at the specified point.
 
 ---
 
+### Weather API Interface
+
+The [`Weather API`](../rest-api/weather_api.md) provides the following functions for use by plugins.
+
+#### `app.emitWeatherWarning = (pluginId, position?, warnings?)`
+
+Weather API interface method for raising, updating and clearing weather warning notifications.
+
+  - `pluginId`: The plugin identifier
+
+  - `position`: A valid `Position` object containing latitude & longitude.
+
+  - `warnings`: An array of `WeatherWarning` objects
+
+- returns:  `void`.
+
+The notification is placed in the path `vessels.self.notifications.weather.warning`.
+
+To raise or update a warning, call the method with a valid `Position` object and array of  `WeatherData` objects.
+
+_Example:_
+```javascript
+app.emitWeatherWarning(
+  'myWeatherPluginId',
+  {latitude: 54.345, longitude: 6.39845},
+  [
+    {
+      "startTime": "2024-05-03T05:00:00.259Z",
+      "endTime": "2024-05-03T08:00:00.702Z",
+      "details": "Strong wind warning.",
+      "source": "OpenWeather",
+      "type": "Warning"
+    }
+  ]
+)
+```
+
+To clear the warning, call the method with an `undefined` position or warnings attribute.
+
+_Example: Clear weather warning_
+```javascript
+app.emitWeatherWarning('myWeatherPluginId')
+```
+
+---
+
+
+### Notifications API _(proposed)_
+
+#### `app.notify(path, value, pluginId)`
+
+Notifications API interface method for raising, updating and clearing notifications.
+
+  - `path`: Signal K path of the notification
+
+  - `value`: A valid `Notification` object or `null` if clearing a notification.
+
+  - `pluginId` The plugin identifier.
+
+
+To raise or update a for a specified path, call the method with a valid `Notification` object as the `value`.
+
+- returns:  `string` value containing the `id` of the new / updated notification.
+
+_Example:_
+```javascript
+const alarmId = app.notify(
+  'myalarm', 
+  {
+	message: 'My cutom alarm text',
+	state: 'alert'
+  },
+  'myAlarmPlugin'
+)
+
+// alarmId = "ac3a3b2d-07e8-4f25-92bc-98e7c92f7f1a"
+```
+
+To clear (cancel) a notification call the method with `null` as the `value`.
+
+- returns:  `void`.
+
+_Example: Clear notification_
+```javascript
+const alarmId = app.notify(
+  'myalarm', 
+  null,
+  'myAlarmPlugin'
+)
+```
+
+---
+
 ### PropertyValues
 
 The _PropertyValues_ mechanism provides a means for passing configuration type values between different components running in the server process such as plugins and input connections.

docs/src/develop/plugins/weather_provider_plugins.md

@@ -0,0 +1,182 @@
+# Weather Provider Plugins
+
+#### (Under Development)
+
+_Note: This API is currently under development and the information provided here is likely to change._
+
+
+The Signal K server [Weather API](../rest-api/autopilot_api.md) will provide a common set of operations for retrieving meteorological data and (like the Resources API) will rely on a "provider plugin" to facilitate communication with the autopilot device.
+
+---
+
+## Provider plugins:
+
+A weather provider plugin is a Signal K server plugin that implements the **Weather Provider Interface** which:
+- Tells server that the plugin is a weather data source
+- Registers the methods used to action requests passed from the server to retrieve data from the weather provider.
+
+_Note: multiple weather providers can be registered._
+
+The `WeatherProvider` interface is defined as follows in _`@signalk/server-api`_:
+
+```typescript
+interface WeatherProvider {
+  name: string
+  methods: WeatherProviderMethods
+}
+```
+where:
+
+- `name`: The weather ssource name. _(e.g. `'OpenWeather'`, `'Open-Meteo'`)_ 
+
+- `methods`: An object implementing the `WeatherProviderMethods` interface defining the functions to which requests are passed by the SignalK server. _Note: The plugin __MUST__ implement each method, even if that operation is NOT supported by the plugin!_
+
+The `WeatherProviderMethods` interface is defined as follows in _`@signalk/server-api`_:
+
+```typescript
+interface WeatherProviderMethods {
+  getData: (position: Position) => Promise<WeatherProviderData>
+  getObservations: (
+    position: Position
+  ) => Promise<WeatherData[]>
+  getForecasts: (position: Position) => Promise<WeatherData[]>
+  getWarnings: (position: Position) => Promise<WeatherWarning[]>
+}
+```
+
+_**Note: The Weather Provider is responsible for implementing the methods and returning data in the required format!**_
+
+
+
+### Provider Methods:
+
+**`getData(position)`**: This method is called when a request to retrieve weather data for the provided position is made.
+
+
+- `position:` Object containing the location of interest. _e.g. {latitude: 16.34765, longitude: 12.5432}_
+
+returns: `Promise<WeatherProviderData>`
+
+_Example: Return weather information for location {latitude: 16.34765, longitude: 12.5432}:_ 
+```
+GET /signalk/v2/api/weather?lat=6.34765&lon=12.5432
+```
+_WeatherProvider method invocation:_
+```javascript
+getData({latitude: 16.34765, longitude: 12.5432});
+```
+
+_Returns:_
+```JSON
+{
+  "id": "df85kfo",
+  "position": {"latitude": 16.34765, "longitude": 12.5432},
+  "observations": [...],
+  "forecasts": [...],
+  "warnings": [...]
+}
+```
+
+---
+
+**`getObservations(position)`**: This method is called when a request to retrieve observation data for the provided position is made.
+
+
+- `position:` Object containing the location of interest. _e.g. {latitude: 16.34765, longitude: 12.5432}_
+
+
+returns: `Promise<WeatherData[]>`
+
+
+_Example: Return observations for location {latitude: 16.34765, longitude: 12.5432}:_ 
+```
+GET /signalk/v2/api/weather/observations?lat=6.34765&lon=12.5432
+```
+
+_WeatherProvider method invocation:_
+```javascript
+getObservations({latitude: 16.34765, longitude: 12.5432});
+```
+
+_Returns:_
+```JSON
+[
+    {
+        "date": "2024-05-03T06:00:00.259Z",
+        "type": "observation",
+        "outside": { ... }
+    },
+    {
+        "date": "2024-05-03T05:00:00.259Z",
+        "type": "observation",
+        "outside": { ... }
+    }
+]
+```
+
+---
+
+**`getForecasts(position)`**: This method is called when a request to retrieve observation data for the provided position is made.
+
+
+- `position:` Object containing the location of interest. _e.g. {latitude: 16.34765, longitude: 12.5432}_
+
+returns: `Promise<WeatherData[]>`
+
+
+_Example: Return forecasts for location {latitude: 16.34765, longitude: 12.5432}:_ 
+```
+GET /signalk/v2/api/weather/forecasts?lat=6.34765&lon=12.5432
+```
+
+_WeatherProvider method invocation:_
+```javascript
+getForecasts({latitude: 16.34765, longitude: 12.5432});
+```
+
+_Returns:_
+```JSON
+[
+    {
+        "date": "2024-05-03T06:00:00.259Z",
+        "type": "point",
+        "outside": { ... }
+    },
+    {
+        "date": "2024-05-03T05:00:00.259Z",
+        "type": "point",
+        "outside": { ... }
+    }
+]
+```
+
+---
+
+**`getWarnings(position)`**: This method is called when a request to retrieve warning data for the provided position is made.
+
+- `position:` Object containing the location of interest. _e.g. {latitude: 16.34765, longitude: 12.5432}_
+
+returns: `Promise<WeatherWarning[]>`
+
+
+_Example: Return warnings for location {latitude: 16.34765, longitude: 12.5432}:_ 
+```
+GET /signalk/v2/api/weather/warnings?lat=6.34765&lon=12.5432
+```
+_WeatherProvider method invocation:_
+```javascript
+getWarnings({latitude: 16.34765, longitude: 12.5432});
+```
+
+_Returns:_
+```JSON
+[
+  {
+    "startTime": "2024-05-03T05:00:00.259Z",
+    "endTime": "2024-05-03T08:00:00.702Z",
+    "details": "Strong wind warning.",
+    "source": "OpenWeather",
+    "type": "Warning"
+  }
+]
+```

docs/src/develop/rest-api/weather_api.md

@@ -0,0 +1,61 @@
+# Weather API
+
+#### (Under Development)
+
+_Note: This API is currently under development and the information provided here is likely to change._
+
+The Signal K server Weather API will provide a common set of operations for interacting with weather sources and (like the Resources API) will rely on a "provider plugin" to facilitate communication with the weather source.
+
+The Weather API will handle requests to `/signalk/v2/api/weather` paths and pass them to an Weather Provider plugin which will return data fetched from the weather service. 
+
+The following operations are an example of the operations identified for implementation via HTTP `GET` requests:
+
+```javascript
+// fetch weather data for the provided location
+GET "/signalk/v2/api/weather?lat=5.432&lon=7.334" 
+```
+
+```javascript
+//  Returns an array of observations for the provided location
+GET "/signalk/v2/api/weather/observations?lat=5.432&lon=7.334"
+```
+
+```javascript
+// Returns an array of forecasts for the provided location
+GET "/signalk/v2/api/weather/forecasts?lat=5.432&lon=7.334" 
+```
+
+```javascript
+// Returnsjavascript an array of warnings for the provided location
+GET "/signalk/v2/api/weather/warnings?lat=5.432&lon=7.334"
+```
+
+The Weather API supports the registration of multiple weather provider plugins. The first plugin registered is set as the default source for all API requests.
+
+A list of the registered providers can be retrieved using a HTTP `GET` request to `/signalk/v2/api/weather/providers`.
+
+```javascript
+GET "/signalk/v2/api/weather/providers"
+```
+
+_Example response:_
+```JSON
+{
+    "providerId1": { 
+        "name":"my-provider-1",
+        "isDefault":true
+    },
+    "providerId2": {
+        "name":"my-provider-2",
+        "isDefault":false
+    }
+}
+```
+
+The provider can be changed to another of those listed by using a HTTP `POST` request and supplying the provider identifier in the body of the request:
+
+```javascript
+POST "/signalk/v2/api/weather/providers" {
+    "id": "providerId2"
+}
+```