@meri-imperiumi/signalk-logbook NPM

Semi-automatic logbook for Signal K

Status: ready for the first test runs

This application provides both a server-side plugin and the user interface for maintaining semi-automatic logbooks with Signal K. Just like traditional logbooks, you can write an entry at any time. However, there are several things that are done automatically for you:

Entries written when starting/ending a trip (requires signalk-autostate plugin)
When underway, an entry is created every hour recording the current conditions

User interface

The logbook presents a web-based user interface as part of the Signal K administration interface. The features should work fine on both desktop and mobile browsers.

Adding a log entry: Add entry

Traditional logbook view: Logbook as table Editing an entry

Log entries on a map: Map view

Registering sail changes: Sails editor

Data storage and format

This logbook app writes the logs to disk using YAML format which combines machine readability with at least some degree of human readability.

Logs are stored on a file per day basis at ~/.signalk/plugin-config-data/signalk-logbook/YYYY-MM-DD.yml If there are no entries for a given day, no file gets written.

Note: unlike Signal K itself, the log entries are written using "human-friendly" units, so degrees, knots, etc. They look something like:

- datetime: 2014-08-15T19:00:19.546Z
  position:
    longitude: 24.7363006
    latitude: 59.7243978
    source: GPS
  heading: 202
  course: 198
  speed:
    stw: 12.5
    sog: 11.8
  log: 9.6
  waypoint: null
  barometer: 1008.71
  wind:
    speed: 13.7
    direction: 283
  engine:
    hours: 405
  category: navigation
  text: Set 1st reef on mainsail
  author: bergie

It is a good idea to set up automatic backups of these files off the vessel, for example to GitHub or some other cloud storage service. How to handle this backup is out of the scope of this plugin.

Source data

The following SignalK paths are used by this logbook.

SingleK path	Timeline name	YAML path	Notes
`navigation.datetime`	Time	`/datetime`	Falls back to system time if not present. Display timezone can be configured.
`navigation.courseOverGroundTrue`	Course	`/course`
`navigation.headingTrue`	Heading	`/heading`
`navigation.speedThroughWater`		`/speed/stw`
`navigation.speedOverGround`	Speed	`/speed/sog`
`environment.wind.directionTrue`	Wind	`/wind/direction`
`environment.wind.speedOverGround`	Wind	`/wind/speed`
`environment.outside.pressure`	Baro	`/barometer`
`environment.water.swell.state`	Sea	`/observations/seaState`
`navigation.position`	Coordinates	`/position/longitude` `/position/latitude`
`navigation.gnss.type`	Fix	`/position/source`	Defaults to "GPS".
`navigation.log`	Log	`/log`
`propulsion.*.runTime`	Engine	`/engine/hours`
`sails.inventory.*`			Sail changes are logged.
`communication.crewNames`		`/crewNames`	Crew changes are logged.
`steering.autopilot.state`			Autopilot changes are logged.
`navigation.state`			If present, used to start and stop automated hourly entries. Changes are logged.
`propulsion.*.state`			Propulsion changes are logged.
`communication.vhf.channel`		`/vhf`
`navigation.courseRhumbline.nextPoint.position`		`/waypoint`

The signalk-derived-data and signalk-path-mapper plugins are both useful to remap available data to the required canonical paths.

API

Other applications can also use the logbook API for retrieving and writing log entries. This can be useful for automations with Node-Red or NoFlo etc.

Ideas

Some additional ideas for the future:

Enable creating additional rules for automated entries when certain things happen (for example, when turning on a watermaker).
We could ship easy systemd unit files for setting up backups to popular locations, like pushing to a git repo
One-time script for populating logbook from InfluxDB entries when starting to use the system

Changes

0.7.1 (2024-04-23)
- Allow storing log entries when VHF channel is a single digit one
0.7.0 (2023-04-27)
- Time range filter for logs to show is now editable (and persisted)
0.6.1 (2023-04-05)
- Motor start/stop is not logged separately when under way as it will change vessel state and produce a log that way
0.6.0 (2023-04-05)
- Course over ground is now also stored in the log data. It is shown instead of heading when available
- Logbook view was made more compact by combining wind and weather observation columns
- Compability with older Node.js versions, like the one on Venus OS
- The "log" data now uses navigation.log instead of navigation.trip.log
0.5.0 (2023-03-13)
- Timezone used when displaying entries is now configurable in plugin settings. Still defaults to UTC.
- Observations form is shown only for navigation entries to reduce clutter
0.4.2 (2023-03-08)
- Fixed issue when there is no recorded speed in a log entry
0.4.1 (2023-03-06)
- Fixed issue when plugin has no configuration
- Enabled Edit button for sails editor when no sails are set as active
0.4.0 (2023-03-05)
- User interface and logging for sail changes, powered by the sailsconfiguration plugin
- User interface and logging for crew changes
- User interface for recording weather observations (sea state, cloud coverage, visibility)
- User interface for recording manual fixes when using celestial navigation etc
- Fix for logbook view when there is no wind data available
0.3.0 (2023-02-22)
- Map view now fetches vessel track using the Signal K History API, if available
- Fixed engine name capture for automatic logs
- Added OpenAPI for easier Logbook API discoverability and usage
0.2.1 (2023-02-15)
- Added triggers for automatically logging when engine is started or stopped
- Added VHF channel to radio logs. Automatically populated when available (see for example the Icom M510e plugin)
0.2.0 (2023-02-15)
- Added support for multiple entry categories (navigation, engine, etc)
- Automatic entry creation when changing autopilot state
- Added an end flag to entries marking end of a trip
- Added engine hours to logs
0.1.2 (2023-02-08)
- Implemented entry deletion
- Fixed issue with initial load if logging in within this webapp (#5)
0.1.0 (2023-02-03)
- Initial release