ca-reports v1.1.0

Signal K Node server Cruising Association plugin

Signal K Node server plugin to provide facility to download and furnish CA Reports through the SK API.

Usage

1. Install "CA Reports" plugin from Signal K Appstore

2. Add your CA Username and Password to the Server config options.

3. Set the default distance value for notes to be retrieved. (The client can override this)

4. Activate plugin

5. Use one of the client apps supporting Signal K notes, for example:

• Freeboard SK

Note: This plugin uses sqlite3, which can take some time to install on a Raspberry PI.

API

Plugin adds support for /resources/notes endpoints described in Signal K specification:

• GET /signalk/v1/api/resources/notes/ returns metadata for all available notes within preset radius of current vessel position
• GET /signalk/v1/api/resources/notes/?position=<lat>,<long>&dist=nn returns metadata for all notes within a radius of nominated position
• GET /signalk/v1/api/resources/notes/<uuid> returns data for selected note
• GET /signalk/v1/api/resources/notes?group=<group id> returns list of notes matching . This tag will override any position tag.

It also supports new notes:

• POST /signalk/v1/api/resources/notes/ send new note detail in SK format

Edited notes:

• PUT /signalk/v1/api/resources/notes/ send updated note detail in SK format

To Delete a note:

• DELETE /signalk/v1/api/resources/notes/<uuid> delete selected notes (if allowed)

Developing against CA Notes

Displaying Notes

CA Notes adopt the topic+comment format, where the 'first' note in a sequence is the topic (also called group id). There may be subsequent notes for the same position, these are recalled using the group tag. Users can create, edit, and delete their own notes, but not those belonging to others. The 'content' for all CA notes is in the 'description' tag. All notes are HTML. All notes will have properties:{readOnly=true} except those that are created by this user, in which case readOnly= false. Users can create 'draft' notes by setting properties:{draft=true}. Draft notes are held within the SK Server cache and not sent to the CA.

The server periodicaly re-syncs with the CA and updates its internal cache of Notes. Notes are being constantly created, edited and deleted by other Users and CA Editors.

1. Send a GET with ?position=<lat,long>&dist=nnn

This wil return a list of notes each with a position, within a radius of 'dist'. If one or more of these parameters are not specified, the system will use the vessel's current position and the default radius set on the Plugin. Use the returned list to plot markers on the screen. Each note will also contain a Group ID. When a user clicks on the marker, create a popup with a 'more info' link (or equivalent).

2. Send a GET with ?group=

This returns a list of notes for that group, which should be displayed on the screen.

Creating New Notes

Users can create new 'topics' by POSTing a new note with a position, but no group id. Topics must be at leats 10 words long. To add a note to an existing group, provide the existing group tag in the new Note.

Editing Existing Notes

Users can edit a note by PUTing an updated note. The server will return a PENDING/202 status while it proceses the Note. The client should then poll the link provided in the PENDING response until either a SUCCESS or ERROR is returned. Users must log into the SK Server to carry out this transaction. Users can 'move' their own notes by sending an Edit with a new Position. Only topic notes can be moved.

Deleting a Note

Send a DELETE with the Note's uuid. At present you cannot delete a 'topic' unless it is a draft.

License

Copyright 2019 Cruising Association

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.