1,388
edits
Logbook Add-on: Difference between revisions
Jump to navigation
Jump to search
no edit summary
No edit summary |
No edit summary |
||
| Line 6: | Line 6: | ||
| developedby = Roman Ludwicki (PlayeRom, SP-ROM) | | developedby = Roman Ludwicki (PlayeRom, SP-ROM) | ||
| initialrelease = December 11, 2022 | | initialrelease = December 11, 2022 | ||
| latestrelease = | | latestrelease = 2.0.0, February 28, 2025 | ||
| writtenin = Nasal | | writtenin = Nasal | ||
| developmentstatus = Advanced production | | developmentstatus = Advanced production | ||
| Line 14: | Line 14: | ||
}} | }} | ||
'''Logbook''' is a FlightGear add-on for automatically logbook all your flights to CSV file. The add-on also provides a Canvas graphical interface for viewing, editing the logbook and showing total statistics. | '''Logbook''' is a FlightGear add-on for automatically logbook all your flights to SQLite/CSV file. The add-on also provides a Canvas graphical interface for viewing, editing the logbook and showing total statistics. | ||
= Installation = | |||
Installation is standard: | |||
# [https://github.com/PlayeRom/flightgear-addon-logbook/releases Download] latest releases version of "Logbook" add-on and unzip it. | |||
# In Launcher go to "Add-ons" tab. Click "Add" button by "Add-on Module folders" section and select folder with unzipped "Logbook" add-on directory (or add command line option: <code>--addon=/path/to/logbook</code>), and click "Fly!". | |||
= How it's working? = | = How it's working? = | ||
| Line 26: | Line 32: | ||
= Logbook file = | = Logbook file = | ||
You | For FlightGear version 2024.1 and later, the logbook is saved to a database file <code>logbook.sqlite</code>. For older versions, up to 2020.3, it is a <code>logbook-v5.csv</code> file. | ||
You can find these files in the <code>[[$FG_HOME]]/Export/Addons/org.flightgear.addons.logbook/</code> directory, where [[$FG_HOME]] on Windows is: | |||
<code>C:\Users\{user name}\AppData\Roaming\flightgear.org\</code> | <code>C:\Users\{user name}\AppData\Roaming\flightgear.org\</code> | ||
on macOS: | |||
<code>/Users/{user name}/Library/Application Support/FlightGear/</code> | |||
on Linux: | |||
<code>/home/{user name}/.fgfs/</code> | <code>/home/{user name}/.fgfs/</code> | ||
For CSV file, you can always open it and edit by any spreadsheet program like LibreOffice Calc, MS Excel, etc. However please don't put the characters <code>,</code> in the cells, because the Logbook parser will recognize them as a column separator, which will cause errors in the operation of the add-on. It is safer to edit the log data through the GUI in the simulator. | |||
The SQLite file can also be edited using special database software such as "DB Browser for SQLite" (DB4S) or "DBeaver". To obtain data for further processing in a spreadsheet, use the "Logbook" -> "Export to CSV" menu (see Export database to CSV file.) | |||
= Migrating CSV to SQLite = | |||
When you run Logbook version 2.x on FlightGear version 2024.1.x or later first time, it will automatically migrate your log data from the CSV file to the SQLite database file. This doesn't require any intervention. | |||
= Logbook file structure = | = Logbook file structure = | ||
| Line 40: | Line 58: | ||
The following information is logged into the file: | The following information is logged into the file: | ||
# <code> | # <code>Real date & time</code> – aircraft take-off date and time. This is the time taken from your OS, not the time in the simulator. This date and time is displayed in the GUI as default. In the settings you can choose what date and time you want to display in the Logbook window. | ||
# <code> | # <code>Sim UTC date & time</code> – aircraft take-off date and time as UTC time in simulator. This date and time is available only in version with SQLite (2024.1+). | ||
# <code>Sim local date & time</code> – aircraft take-off date and time as local time in simulator. This date and time is available only in version with SQLite (2024.1+). | |||
# <code>Aircraft</code> – the code name of the aircraft. | # <code>Aircraft</code> – the code name of the aircraft. | ||
# <code>Variant</code> – the code name of the aircraft as its variant. Some aircraft are available in several variants, such as the default "Cessna 172P", which includes different variants like "Cessna 172P Float". If you select "Cessna 172P," you will see <code>c172p</code> in the <code>Aircraft</code> as well as <code>Variant</code> column. If you select the float variant ("Cessna 172P Float"), you will see <code>c172p</code> in the Aircraft column, but <code>c172p-float</code> in the <code>Variant</code> column. This way you have the main group of aircraft in the <code>Aircraft</code> column, and its variants in the <code>Variant</code> column. This will allow you to extract <code>Totals</code> statistics for a general group of aircraft no matter what variant (filtering by <code>Aircraft</code>), as well as more precisely for a specific variant of a given aircraft (filtering by <code>Variant</code>). | # <code>Variant</code> – the code name of the aircraft as its variant. Some aircraft are available in several variants, such as the default "Cessna 172P", which includes different variants like "Cessna 172P Float". If you select "Cessna 172P," you will see <code>c172p</code> in the <code>Aircraft</code> as well as <code>Variant</code> column. If you select the float variant ("Cessna 172P Float"), you will see <code>c172p</code> in the Aircraft column, but <code>c172p-float</code> in the <code>Variant</code> column. This way you have the main group of aircraft in the <code>Aircraft</code> column, and its variants in the <code>Variant</code> column. This will allow you to extract <code>Totals</code> statistics for a general group of aircraft no matter what variant (filtering by <code>Aircraft</code>), as well as more precisely for a specific variant of a given aircraft (filtering by <code>Variant</code>). | ||
| Line 71: | Line 90: | ||
# <code>Fuel</code> – total amount of fuel burned in flight, in U.S. gallons. | # <code>Fuel</code> – total amount of fuel burned in flight, in U.S. gallons. | ||
# <code>Max Alt</code> – maximum altitude, in feet, reached during flight. | # <code>Max Alt</code> – maximum altitude, in feet, reached during flight. | ||
# <code>Max groundspeed</code> – maximum groundspeed, in knots, reached during flight. | |||
# <code>Max Mach</code> – maximum speed in Mach number reached during flight. | |||
# <code>Note</code> – notes, by default the full name of the aircraft. '''This is a good place to enter your own notes as well'''. | # <code>Note</code> – notes, by default the full name of the aircraft. '''This is a good place to enter your own notes as well'''. | ||
= Viewing the logbook = | = Viewing the logbook = | ||
The add-on also provides the ability to view the entire flight logbook from the simulator. You should select "Logbook" -> "Logbook" from the menu. The main window will open with the entire logbook in tabular form. The last row signed "Totals", contains a summary, not only of the visible entries on a given page, but of the entire logbook. The same "Totals" row is visible on every page. The exception for totals is the | The add-on also provides the ability to view the entire flight logbook from the simulator. You should select "Logbook" -> "Logbook" from the menu. The main window will open with the entire logbook in tabular form. | ||
The last row signed "Totals", contains a summary, not only of the visible entries on a given page, but of the entire logbook. The same "Totals" row is visible on every page. The exception for totals is the Max Alt, Max GS and Max Mach columns, in which you don't have the sum of all values, but the highest one. | |||
At the very bottom | At the very bottom there is a row of buttons, mainly for moving through the log pages: | ||
# <code>|<<</code> – button for moving to the first page, | |||
# <code><</code> – moving to the previous page, | |||
# <code>></code> – moving to the next page, | |||
# <code>>>|</code> – moving to the last page. | |||
In the middle there is text information in the format <code>{on which page you are} / {number of all pages}</code> (number of entries in the log). On the right is the <code>dark/light</code> button to switch between window styles. The <code>≡</code> button opens a windows with settings, and the last <code>?</code> button opens a window with help (the same as from the "Logbook" -> "Help" menu). | |||
== Data filtering == | == Data filtering == | ||
The | The addon allows you to filter some columns in the main log window. At the moment you can filter by the "Date" (as a year), "Aircraft", "Variant", "Type", "Callsign", "From", "To", "Landing" and "Crash" columns. To use filtering, hover the mouse cursor over a column name (it will be highlighted) and click it. A new window will appear with a choice of values. | ||
For filtering on the "Aircraft" column, these will be the IDs of aircraft you have flown before. For filtering by the "Type" column, these will be the names of aircraft types, etc. Each window with filters also has the "All" position, which means that the filter will be turned off and all items will be shown. When the filter is enabled, an asterisk (<code>*</code>) sign will be shown next to the filtered column to warn that the filter has been used. | |||
After using the filter, the "Totals" row will also be updated with the filtered data. In this way, you can see statistics for a specific aircraft or types of aircraft. | After using the filter, the "Totals" row will also be updated with the filtered data. In this way, you can see statistics for a specific aircraft or types of aircraft. | ||
== Details of entry logbook == | |||
Each log entry in the main window can be hovered over and clicked. Then an additional window will open presenting the details of the given entry. | |||
In general, you have the same information here as in the main window, except: | |||
# you can see three dates and times of aircraft takeoff: | |||
#* real date & time from your OS, | |||
#* UTC date & time from the simulator, | |||
#* local date & time from the simulator; | |||
# ICAO airport codes include their names in parentheses; | |||
# with numerical data, you are given the units in which these values are presented with conversions to other units; | |||
# at the very bottom you have an additional Note field, which is not displayed in the main window, due to the possibility of placing any length of text here. | |||
== Editing and deleting data == | == Editing and deleting data == | ||
Each logbook entry can be edited from the simulator. You need to select "Logbook" -> "Logbook" from the menu. The main window with the entire logbook will open. Here you can search for the entry you want to edit and click on it. The details window for the entry will open. Now you can click on the specific entry you want to edit. Another window with a text field will open. Just enter the new value and confirm with the "Save" button. The change will immediately be saved to a file. | |||
At the bottom of the details window there is a Delete button, with which you can permanently delete the selected entry. | |||
== Flight Analysis == | |||
The details window of logbook also contains an <code>Analysis</code> button. Once you click on it, a new window will open with the flight analysis. | |||
The window is divided into two parts, the upper one with the map (lateral navigation) and the lower one with the profile (vertical navigation). The path along which the flight was made is drawn in blue. The brown path on the profile is the terrain elevation. | |||
Flight analysis can also be opened from the "Logbook" -> "Current Flight Analysis" menu. The difference is that this analysis always comes from your current session. The difference in operation is that in "Current Flight Analysis" you cannot change the zoom level for the vertical profile. | |||
Flight analysis from the logbook will only be available for flights made in FlightGear 2024.1 and later. Current session analysis is available from FlightGear 2020. | |||
The flight analysis window is resizable, but remember that if it is too small it will not be able to draw the map or vertical profile correctly. | |||
At the bottom we have a number of elements to control the flight analysis: | |||
=== Zoom === | |||
You can change the vertical profile zoom using the <code>-</code>/<code>+</code> buttons. You can also do this using the mouse wheel when the cursor is over the graph. The zoom range is: 1x (the entire graph is visible), 2x (the graph is divided into 2 parts), 4x (division into 4 parts), 8x (division into 8 parts) and a maximum of 16x (division into 16 parts). The current zoom level is indicated by the text between the buttons. However, please note that the maximum zoom may be reduced if the number of recorded track points is too small. | |||
The map view can also be zoomed using the mouse wheel. There are no buttons here but there are zoom level indicators in the upper left corner of the map. The zoom range for map is from 3 to 14. The default zoom level is set to 10. If the flight path does not fit on the map, you must zoom out of the map view or move the airplane along the path by click on the path or by using the <code><</code> and <code>></code> buttons to see the rest of the path. | |||
=== Frame === | |||
Information about where the aircraft icon is currently located on the flight path, among all recorded flight path points. The currently selected point is marked with the airplane icon both on the map and the profile. By default, the aircraft icon is positioned at the first point, i.e. at the beginning of the flight. | |||
=== Player === | |||
Next we have a series of buttons to control the animation and movement of the aircraft icon along the recorded flight path points: | |||
* <code>|<<</code> and <code>>>|</code> – jump to start or end point. | |||
* <code><<</code> and <code>>></code> – move back or forward 10 points. | |||
* <code><</code> and <code>></code> – move back or forward 1 point. | |||
* <code>Play</code>/<code>Stop</code> – start/stop flight animation of airplane icon. | |||
To change airplane icon position, you can also click on the map near to the fly path or click on the profile graph. Then the airplane icon will be moved to the closest point to the click location. | |||
=== Speed === | |||
With the "Speed" option you can change the animation speed of the airplane icon movement, where <code>1x</code> is the real-time flight speed, up to a maximum of <code>32x</code> faster. This option is only available from FlightGear version 2024.1. Older versions use a fixed animation speed of <code>16x</code> (because the GUI doesn't include a combobox.) | |||
=== Profile mode === | |||
At the bottom right there is also an option to change the profile drawing mode. In FlightGear version 2024.1, this is a combobox with the options "distance" and "time". This option defines whether the X-axis should be drawn based on time or distance traveled. | |||
When based on time, the graph will be evenly and linearly distributed, even when the aircraft is stationary or hovering because time is always moving forward. So the graph won't show where the flight was faster or slower, but you will avoid overlapping points. | |||
When based on distance, the points will be drawn close to each other or overlapping when the aircraft is stationary or flying slowly, but they will be more spread out when flying fast, making it possible to recognize places where the flight was performed at higher speeds and where at lower ones. In FlightGear versions older than 2024, this option is presented as a check box. When you check it, you will enable "time" mode (default is "distance" mode). | |||
=== Information about each point === | |||
To the left of the map, there is recorded information about the given path point where the airplane icon is currently located, and these are: | |||
* geographical coordinates of the point, | |||
* altitude MSL and AGL at which the aircraft was located, | |||
* true and magnetic heading that the aircraft was flying at the given point, | |||
* airspeed and groundspeed in knots that the aircraft was flying at the given point, | |||
* direction from which the wind is blowing and its speed in knots, | |||
* flight time at the given point, | |||
* distance traveled at the given point. | |||
=== Map view === | |||
The map shows the aircraft's position and heading. | |||
The path the aircraft flew is drawn with a blue line. | |||
In the upper left corner you have information about the map zoom level. Below are the following buttons: | |||
* OpenStreetMap – change map provider to OpenStreetMap | |||
* OpenTopoMap – change map provider to OpenTopoMap | |||
In the upper right corner you have information about wind direction and speed (wind barbs). | |||
Click near the path on the map to move the airplane icon there. | |||
Scroll on the map to change map zoom level. | |||
=== Vertical profile graph view === | |||
The vertical profile shows a side view of our flight, where the vertical axis shows altitude in feet, the horizontal axis contains two values. The first is time in hours, the second below is distance in NM. | |||
The blue line is the flight path, the brown line is the elevation of the terrain. | |||
Click on the graph to move airplane icon position. | |||
Scroll on the graph to change zoom level. | |||
= Settings = | |||
When you click on the <code>≡</code> button in the Logbook view, the settings window will open. | |||
Here you can configure the following options: | |||
# <code>Date and time displayed in the Logbook view</code> – Logbook window shows only one <code>Date</code> and <code>Time</code> item, but triple dates and times are logged, so here you can choose which one you want to display in Logbook window, by default it is real time, taken from your operating system. These options are only available for FG >= 2024.1. | |||
# <code>Columns to display in the Logbook view</code> – here you can specify which columns are to be displayed in the Logbook window. Columns such as <code>Date</code>, <code>Time</code> and <code>Aircraft</code> are always displayed, the Note column will never be displayed and this cannot be changed. These options are only available for FG >= 2024.1. | |||
# <code>Map provider</code> – here you can specify default map tile provider in the Flight Analysis view. Available providers are <code>OpenStreetMap</code> and <code>OpenTopoMap</code>, | |||
# <code>Click sound</code> – by default, a sound is played when you click on various buttons, you can turn this sound off here. | |||
# <code>Items per page</code> – here you can specify how many rows of logs should be displayed in the Logbook view, the default is 10. | |||
# <code>Optimize database</code> – this button will defragment the database file (sqlite), which will speed up database operations and reduce its size on the disk. These option is only available for FG >= 2024.1. | |||
== Advance settings == | |||
When you close the simulator, the settings will save to the <code>autosave_{version}.xml</code> file in [[$FG_HOME]] location. By editing this file you can configure more options. First, find the <code>org.flightgear.addons.logbook</code> tag, which will contain the following settings: | |||
# <code>tracker-interval-sec</code> – real number as the number of seconds every which data will be dumped for flight analysis. The smaller the number, the more data you will receive and the flight analysis will be more accurate, therefore the database file will take up more space and the processor may be a little more loaded. If you are making a long flight on an airliner, a value of 20 seconds should be satisfactory. If you want to perform aerobatics and want to analyze your flight in detail, you can set this value even to 1 second. A value less than 1 second (this is the default) means automatic mode, i.e. the add-on will dynamically adjust the time interval seconds. By default, it will be 15 seconds, but during turns, i.e. bank greater than 5 degrees and at an altitude of less than 2000 ft above ground level, the interval will change to 5 seconds. Thanks to this, flight close to the terrain will be recorded more accurately and turns on the map will be more rounded. | |||
# <code>real-time-duration</code> – if true then time spent in flight is always real time, i.e. speeding up or slowing down the simulation time will not affect Duration (default true). So if your flight would take 2 hours but you accelerate the time in the simulator 2x, then you will fly in 1 real hour and the log will record 1 hour of flight. On the other hand, if you set this option to false, then in this case 2 hours would be logged, according to the simulator time. | |||
and settings available from GUI: | |||
# <code>dark-style</code> – if true then dark theme is using (default false). | |||
# <code>sound-enabled</code> – if true then click sound will be playing (default true). | |||
# <code>date-time-display</code> – which time will be displaying in main Logbook table. Possible values: | |||
#* <code>real</code> – your real time, from your OS, | |||
#* <code>sim-utc</code> – UTC time in simulator, | |||
#* <code>sim-local</code> – local time in simulator. | |||
# <code>log-items-per-page</code> – integer number as how many rows of logs should be displayed in the Logbook view (default 20). | |||
# <code>columns-visible</code> – which column should be visible in main Logbook view. | |||
# <code>map-provider</code> – the default map tile provider used when the Flight Analysis window is opened. Possible values: | |||
#* <code>OpenStreetMap</code> – default, | |||
#* <code>OpenTopoMap</code>. | |||
NOTE. Before editing the <code>autosave.xml</code> file, close the simulator. | |||
= Backup (for FG 2020.3 and older) = | |||
If you edit logbook entries via GUI, then before each saving of a single change, the add-on creates a copy of the original CSV file, to which it appends the <code>.bak</code> extension at the end. So, if something goes wrong while editing the data and the original file is corrupted, you can always recover it by removing the <code>.bak</code> suffix from the copy name. Remember that you only have a copy of the last one file operation. | |||
For the newer version (2024.1 and later) based on the SQLite database, the backup copy is unnecessary as the database engine takes care of the correctness of the record. | |||
= | = Recovery mode = | ||
== For FG 2020.3 and older == | |||
This add-on includes a mechanism to save the current flight status to a separate <code>recovery-v5.csv</code> file every 30 seconds. If FlightGear unexpectedly closes due to an error, this file will be read on reboot and an entry from this file will be moved to the main log file. In this way, no flight, even aborted, should be lost. | |||
== For FG 2024.1 and later == | |||
In the newer version based on the SQLite database, the recovery mechanism writes data every 20 seconds directly to the main database, so data will be preserved even if FlightGear crashes and that data will be available for viewing during flight. | |||
= Export database to CSV file (2024.1 and later) = | |||
For FlightGear 2024.1 and newer, the add-on provides an "Export to CSV" menu item that will export all data from the SQLite database to a CSV file, allowing you to process this data in a spreadsheet. | |||
This option will create two CSV files: | |||
# the first in the format <code>export-YYYY-MM-DD-HH-mm-SS-logbook.csv</code> (suffix "logbook") for the Logbook table, | |||
# the second <code>export-YYYY-MM-DD-HH-mm-SS-tracker.csv</code> (suffix "tracker") for the flight analysis table. | |||
The relationship between the files is that the "tracker" CSV file contains a <code>Logbook ID</code> column that contains the <code>ID</code> column identifiers from the "logbook" CSV file. | |||
These files will be saved in the same directory as the SQLite file. The timestamp is taken from the time the export was made and is identical for both related files. | |||
= Note = | = Note = | ||
# If you properly close the simulator during the flight ("File" -> "Exit"), the current flight status will be saved to the logbook (without landing information, of course). | # If you properly close the simulator during the flight ("File" -> "Exit"), the current flight status will be saved to the logbook (without landing information, of course). | ||
# If the simulator will be closed incorrectly during flight, e.g. via the [X] button on the window bar, or a crash occurs, the logbook data should be saved in the <code>recovery.csv</code> file. The data in the <code>recovery.csv</code> file will be automatically transferred to the <code>logbook.csv</code> file when the simulator is restarted. | # If the simulator will be closed incorrectly during flight, e.g. via the [X] button on the window bar, or a crash occurs, the logbook data should be saved in the <code>recovery-v5.csv</code> file. The data in the <code>recovery-v5.csv</code> file will be automatically transferred to the <code>logbook-v5.csv</code> file when the simulator is restarted. For version 2024.1 and later, the data is always, cyclically written directly to the SQLite database, so the <code>recovery-v5.csv</code> file is not used. Data for recovery mode is saved every 30 or 20 seconds. | ||
# To count as a landing, the aircraft must rest on all wheels and maintain this state for at least 3 seconds. In this way, an ugly bounce off the runway will not be counted as a landing. | # To count as a landing, the aircraft must rest on all wheels and maintain this state for at least 3 seconds. In this way, an ugly bounce off the runway will not be counted as a landing. | ||
# If you start a simulation in the air, the add-on will recognize this and start logging without waiting for take-off. | # If you start a simulation in the air, the add-on will recognize this and start logging without waiting for take-off. | ||
| Line 124: | Line 305: | ||
= Landing gear hints = | = Landing gear hints = | ||
If this add-on has a problem with recognizing the landing gear correctly, then you can put the appropriate properties to indicate which indexes from <code>/gear/gear[index]</code> are used by the aircraft. | If this add-on has a problem with recognizing the landing gear correctly, then you can put the appropriate properties to indicate which indexes from <code>/gear/gear[index]</code> are used by the aircraft. | ||
| Line 130: | Line 312: | ||
<PropertyList> | <PropertyList> | ||
< | <addons> | ||
< | <by-id> | ||
< | <org.flightgear.addons.logbook> | ||
<landing-gear-idx type="int">12</landing-gear-idx> | <hints> | ||
<landing-gear-idx type="int">12</landing-gear-idx> | |||
</ | <landing-gear-idx type="int">13</landing-gear-idx> | ||
</ | </hints> | ||
</ | </org.flightgear.addons.logbook> | ||
</by-id> | |||
</addons> | |||
</PropertyList> | </PropertyList> | ||