diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/.gitignore | 1 | ||||
| -rw-r--r-- | doc/Makefile.am (renamed from doc/Makefile) | 23 | ||||
| -rw-r--r-- | doc/RELNOTES | 8 | ||||
| -rw-r--r-- | doc/altusmetrum-docinfo.xml | 9 | ||||
| -rw-r--r-- | doc/map-loading.dot | 35 | ||||
| -rw-r--r-- | doc/map-loading.txt | 221 | ||||
| -rw-r--r-- | doc/micropeak-docinfo.xml | 16 | ||||
| -rw-r--r-- | doc/release-notes-1.8.7.inc | 37 | ||||
| -rw-r--r-- | doc/release-notes.inc | 4 | ||||
| -rw-r--r-- | doc/specs.inc | 18 | ||||
| -rw-r--r-- | doc/telegps-docinfo.xml | 10 | ||||
| -rw-r--r-- | doc/telemini.inc | 50 | ||||
| -rw-r--r-- | doc/usage.inc | 19 |
13 files changed, 441 insertions, 10 deletions
diff --git a/doc/.gitignore b/doc/.gitignore index 786123a3..06ad43eb 100644 --- a/doc/.gitignore +++ b/doc/.gitignore @@ -4,3 +4,4 @@ *.raw titlepage.templates.xsl fop-cfg.xml +map-loading.svg diff --git a/doc/Makefile b/doc/Makefile.am index 3661a6d6..450053f1 100644 --- a/doc/Makefile +++ b/doc/Makefile.am @@ -2,7 +2,12 @@ # http://docbook.sourceforge.net/release/xsl/current/README # +if FAKETIME +FAKETIME=TZ=UTC faketime -f '$(RELEASE_DATE) 00:00:00 i0' +endif + RELNOTES_INC=\ + release-notes-1.8.7.inc \ release-notes-1.8.6.inc \ release-notes-1.8.5.inc \ release-notes-1.8.4.inc \ @@ -194,7 +199,8 @@ RELNOTES_HTML=$(RELNOTES_INC:.inc=.html) ONEFILE_TXT_FILES=\ altos.txt \ companion.txt \ - telemetry.txt + telemetry.txt \ + map-loading.txt ONEFILE_RAW_FILES=$(ONEFILE_TXT_FILES:.txt=.raw) ONEFILE_PDF_FILES=$(ONEFILE_TXT_FILES:.txt=.pdf) @@ -215,6 +221,8 @@ HTML_REVHISTORY=\ PDF=altusmetrum.pdf micropeak.pdf telegps.pdf easymini.pdf $(ONEFILE_PDF_FILES) \ $(OUTLINE_PDF_FILES) +MAP_DOT_FILES=map-loading.dot +MAP_SVG_FILES=$(MAP_DOT_FILES:.dot=.svg) FOP_STYLE=am-fo.xsl HTML_STYLE=am-html.xsl COMMON_STYLE=common.xsl @@ -244,7 +252,10 @@ PUBLISH_DOC=$(PUBLISH_HTML) $(HTML_REVHISTORY) $(PDF) $(IMAGES) $(STYLESHEET) DOC=$(HTML) $(HTML_REVHISTORY) $(PDF) $(IMAGES) $(STYLESHEET) -.SUFFIXES: .tmpl .xsl .inc .txt .raw .pdf .html +SUFFIXES = .dot .svg .tmpl .xsl .inc .txt .raw .pdf .html + +.dot.svg: + dot -Tsvg -o$@ $*.dot .txt.raw: sed -e 's/^[ ]*//' -e 's/^\\//' $*.txt > $@ @@ -253,18 +264,20 @@ DOC=$(HTML) $(HTML_REVHISTORY) $(PDF) $(IMAGES) $(STYLESHEET) sed -e 's/^[ ]*//' -e 's/^\\//' $*.inc > $@ .raw.html: - a2x --verbose -a docinfo -f pdf --xsltproc-opts "--stringparam toc.section.depth 2" --xsl-file $(FOP_STYLE) --fop --fop-opts="-c $(FOP_XCONF)" $*.raw - a2x --verbose -a docinfo -f xhtml --xsltproc-opts "--stringparam toc.section.depth 2" --xsl-file $(HTML_STYLE) --stylesheet=$(STYLESHEET) $*.raw + a2x -a docinfo -f xhtml --xsltproc-opts "--stringparam toc.section.depth 2" --xsl-file $(HTML_STYLE) --stylesheet=$(STYLESHEET) $*.raw case $* in release-notes*) ./fix-html $*.html ;; esac + $(FAKETIME) a2x -a docinfo -f pdf --xsltproc-opts "--stringparam toc.section.depth 2" --xsl-file $(FOP_STYLE) --fop --fop-opts="-c $(FOP_XCONF)" $*.raw .html.pdf: - @touch $@ + echo $@ .tmpl.xsl: xsltproc --output $@ /usr/share/xml/docbook/stylesheet/docbook-xsl/template/titlepage.xsl $*.tmpl all: $(HTML) $(PDF) +map-loading.raw: $(MAP_SVG_FILES) + altusmetrum-revhistory.html: altusmetrum.html micropeak-revhistory.html: micropeak.html diff --git a/doc/RELNOTES b/doc/RELNOTES index 748d2b5b..678ac17e 100644 --- a/doc/RELNOTES +++ b/doc/RELNOTES @@ -1,12 +1,12 @@ Creating documentation for a new release of AltOS +* Write release notes in release-notes-${version}.inc. Add to + Makefile + * Make sure that doc/altusmetrum-docinfo.xml has the right copyright year, and add release to the revision history at the front (release notes will be pulled in by release-notes.inc) -* Write release notes in release-notes-${version}.inc. Add to - Makefile - * Add references to that as appropriate from each of the documents: @@ -34,3 +34,5 @@ Creating documentation for a new release of AltOS telemetry-docinfo.xml * Add release-notes-${version}.inc to git + +* Make sure new hardware specs are documented in specs.inc diff --git a/doc/altusmetrum-docinfo.xml b/doc/altusmetrum-docinfo.xml index 7b696b97..18bc644d 100644 --- a/doc/altusmetrum-docinfo.xml +++ b/doc/altusmetrum-docinfo.xml @@ -47,6 +47,15 @@ <revhistory> <?dbhtml filename="altusmetrum-revhistory.html"?> <revision> + <revnumber>1.8.7</revnumber> + <date>8 Oct 2018</date> + <revremark> + Include TeleMega v3.0 firmware in release. Fix TeleBT v4.0 RF + calibration to factory value when reflashing. Fix map images. + Fix Mac OS X support. + </revremark> + </revision> + <revision> <revnumber>1.8.6</revnumber> <date>6 Aug 2018</date> <revremark> diff --git a/doc/map-loading.dot b/doc/map-loading.dot new file mode 100644 index 00000000..f5be02ef --- /dev/null +++ b/doc/map-loading.dot @@ -0,0 +1,35 @@ +digraph map_loading { + edge [arrowsize=0.5; style="setlinewidth(2)"] + node [style=filled; fontcolor=white; color=invis; shape=box; arrowsize=0.5; fontname="DejaVu Sans,sans-serif"; fontsize=12; height=0.2;]; + edge [decorate=true; fontname="DejaVu Sans,sans-serif"; fontsize=8]; + graph [fontname="DejaVu Sans,sans-serif"; fontsize=15; ] + rankdir="TB"; + ranksep=0.5; + nodesep=0.5; + color=invis; + fillcolor="#c0c0c0"; + fontcolor="white"; + + app -> apache [label="AltOS Map URI"] + apache -> app [label="Google Map tile"] + + apache -> cgi_script [label="AltOS Map URI"] + cgi_script -> cache_manager [label="AltOS Tile Request"] + + cgi_script -> apache [label="Google Map tile"] + + cache_manager -> cgi_script [label="AltOS Tile Reply"] + + cache_manager -> disk_files [label="AltOS tile files" dir="both"] + cache_manager -> google_maps [label="Google Map URI"] + + google_maps -> cache_manager [label="Google Map tile"] + + app [color="#885931" label="Application"] + apache [color="#d12127" label="Apache Web Server"] + cgi_script [color="#551a8b" label="AltOS Map CGI Script"] + cache_manager [color="#c75b1c" label="AltOS Map Cache Manager"] + disk_files [color="#4f81bd" label="File System"] + google_maps [color="#4cbb44" label="Google Maps"] +} + diff --git a/doc/map-loading.txt b/doc/map-loading.txt new file mode 100644 index 00000000..1b39dd6b --- /dev/null +++ b/doc/map-loading.txt @@ -0,0 +1,221 @@ += Loading Map Tiles from Google Maps +:doctype: article + +== The Google Maps Problem + +Until recently, Google Maps could be used without fee to fetch map +tiles. Applications could load map tiles anonymously or using a key; +when used anonymously, the number of tiles that could be loaded per +day and the rate at which tiles could be loaded was throttled to make +the API practical only for development purpose. With an application +key, the number of tiles available per day was much higher, and there +was no rate limiting. This was usually sufficient for Altos Metrum +customer use. + +However, this has changed and now there is no way to load map tiles +anonymously, and any application key must be tied to a credit +card. The tile cap for free usage is now monthly instead of +daily. Because the key is tied to a credit card, we should not ship it +with the application any longer. And because the cap is monthly +instead of daily, we need some way to control usage by our +applications. + +=== The Proposed Solution — An Intermediate Service + +To give us some measure of control over tile loading, we will want to +interpose a server controlled by us between the application and Google +Maps. This will let us store the Google Maps key in a secure location, +and also control tile loading by each user. + +image::map-loading.svg[align="center"] + +== AltOS Map Service + +This service receives a URL request and replies with either a map tile +or an error. It is functionally equivalent to the Google Maps service, +except that it can control use of the Google Maps API. + +=== AltOS Map CGI Script + +The AltOS Map CGI Script is a straightforward script which connects to +the AltOS Map Cache Manager, transmits a URL describing the desired +map tile and receives back a filename (or error), then sends the +contents of that file back through Apache to the requesting +application. The name of the script is 'altos-map'. + +==== Inputs + +The AltOS Map CGI Script will parse the provided AltOS Map URI or +AltOS Version URI. + +==== Outputs + +For AltOS Map URLs, the CGI Script will return either the contents of +the associated Google Map tile or an error indicating what failed: + +_200 OK_: The map tile image data or version information + +_400 Bad Request_: The URL is malformed or not compatible with the +version supported by the service + +_403 Forbidden_: The map tile is outside the areas supported by the +current AltOS Map service area + +_408 Request Timeout_: Attempts to fetch the tile from Google Maps +timed out. + +_503 Service Unavailable_: The service is temporarily refusing to +satisfy this request due to resource limitations. + +=== AltOS Map Cache Manager + +This is a service running on the local machine and available over a +local network socket. It translates an AltOS Map URL into a local +filename containing the contents of the associated Google Maps +tile. The name of the cache manager is 'altos-mapd'. It will listen +for requests on port 16717. + +=== AltOS Map URI + +AltOS uses a limited subset of the Google Maps, and the AltOS Map URIs +only encode those elements which we currently use. This specification +describes AltOS Map URI format version 1.0.0. The application is +required to provide URIs compatible with the format supported by the +server. The elements of the elements are: + + * Latitude of center point + * Longitude of center point + * Zoom level (from bushes to planets) + +Encoding this in a URI is straightforward: + +\ altos-map?lat=<lat>&lon=<lon>&zoom=<zoom> + +Latitude and longitude are both encoded using decimal degrees with 6 +digits following the decimal point. + +Zoom levels can range from 1 (world) to 20 (buildings). Higher zoom +levels show smaller areas at greater detail. + +The only Google Map type supported by version 1.0.0 of the service is +“hybrid”, which combines road graphics on top of satellite images. + +Version 1.0.0 always returns images which are 512x512 pixels. + +If we need additional elements in the URL, we can add them in the +future and bump the supported version number. + +=== AltOS Version URI + +To allow applications to discover what AltOS Map URI version is supported by the +AltOS Map service, the application may query the version of the API +supported using the Version URI. The application provides the version +that it supports and the AltOS Map service returns a version not +greater than the client version: + +\ altos-map?version=<client-major>.<client-minor>.<client-revision> +\ → +\ <server-major>.<server-minor>.<server.revision> + +=== AltOS Tile Request + +The AltOS Map CGI Script parses the Map URI and passes that +information to the AltOS Map Cache Manager using the AltOS Tile +Specifier syntax. This is a JSON representation of the same data +provided by the URI: + +\ { +\ "lat": <latitude>, +\ "lon": <longitude>, +\ "zoom": <zoom-level>, +\ "remote_addr": "<IPv4 or IPv6 address of requesting client>" +\ } + +Latitude and longitude are both encoded using decimal degrees with 6 +digits following the decimal point. + +=== AltOS Tile Reply + +Sent back from the Cache Manager to the CGI Script, this encodes the +status of the request and the filename of any tile data available. It +is encoded in JSON format: + +\ { +\ "status": <HTTP status>, +\ "filename": "<absolute path to image file>", +\ "content_type": "<HTTP content-type>" +\ } + +The “filename” and “content-type” elements are only included when +the status is _200 OK_. + +=== AltOS Tile Filename + +While the current AltOS Map URI version only supports a limited subset +of the Google Maps functionality, we'll encode more of that data in +filenames to allow for easy expansion of functionality in the +future. The elements of an AltOS Tile filename consist of : + + * Latitude, with N/S indicator (instead of a sign) + * Longitude, with E/W indicator (instead of a sign) + * Map type. + * Zoom level + * Scale factor. Scale, and the preceding hyphen are omitted for a scale factor of 1. + * Image format suffix. '.jpg' for JPEG files and '.png' for PNG files. + +Latitude and longitude are both encoded using decimal degrees with 6 +digits following the decimal point. + +Map type is one of : + + _hybrid_: Road graphics over satellite images + _roadmap_: Symbolic road map + _satellite_: Un-annotated satellite images + _terrain_: Topographic map + +Here's what map filenames look like: + +\ map-{N,S}<lat>,{E,W}<lon>-<type>-<zoom>[-<scale>].<format> +\ +\ map-N36.508532,W107.823944-hybrid-18.jpg + +To transmit this name from the AltOS Map Cache Manager back to the +Altos Map CGI script, the filename will be wrapped in a JSON string + +== Implementation + +The AltOS Map CGI Script and AltOS Map Cache Manager will both be +implemented in Java as much of the required Google Maps infrastructure +is already available in that language. + +=== Access Control + +No access control to the service is planned at this point. If +necessary, we could implement username/password access control for each +user of the service. + +=== Location Restrictions + +To avoid unbounded usage, and confine the utility of this service to +AltOS users, the service will only offer map tiles whose center +location is within 10 miles of one of the sites registered in +our launch sites database. + +To allow testing of the registered launch site database, a database of +privileged clients will be supported. Privileged clients will have +unlimited access to the service. + +=== Per-Client Restrictions + +We should implement a per-day limit on the number of tiles provided to +a particular requesting client. We can also rate limit clients to a +certain number of tiles per minute to reduce the bandwidth consumed +out of our server. + +=== Cache Lifetime Restrictions. + +The Google Maps API allows for caching of map data for no more than 30 +days. To honor this, the Cache Manager will re-fetch any requested +tiles when the cached version is older than this. If the fetch fails, +the cache manager will continue to serve the data from the cached +version of the file. diff --git a/doc/micropeak-docinfo.xml b/doc/micropeak-docinfo.xml index 37c6e770..6fab12b8 100644 --- a/doc/micropeak-docinfo.xml +++ b/doc/micropeak-docinfo.xml @@ -5,7 +5,7 @@ <email>keithp@keithp.com</email> </author> <copyright> - <year>2014</year> + <year>2018</year> <holder>Keith Packard</holder> </copyright> <mediaobject> @@ -32,6 +32,20 @@ <revhistory> <?dbhtml filename="micropeak-revhistory.html"?> <revision> + <revnumber>1.8.7</revnumber> + <date>8 October 2018</date> + <revremark> + Poll for MicroPeak USB while the device dialog is open. Fix Mac OS X support. + </revremark> + </revision> + <revision> + <revnumber>1.8.6</revnumber> + <date>6 August 2018</date> + <revremark> + Report altimeter-recorded maximum height value + </revremark> + </revision> + <revision> <revnumber>1.3.2</revnumber> <date>12 February 2014</date> <revremark> diff --git a/doc/release-notes-1.8.7.inc b/doc/release-notes-1.8.7.inc new file mode 100644 index 00000000..f8b7b103 --- /dev/null +++ b/doc/release-notes-1.8.7.inc @@ -0,0 +1,37 @@ += Release Notes for Version 1.8.7 +:toc!: +:doctype: article + + Version 1.8.7 + + == AltOS + + * Include TeleMega v3.0 firmware + + == AltosUI, TeleGPS, MicroPeak + + * Poll for new devices while Device dialog is displayed + + * Wait for device to re-appear when flashing new firmware + + * Fetch correct TeleBT v4.0 RF calibration values from web + site when reflashing. + + * Change gyro headings in .csv files from x/y/z to + roll/pitch/yaw + + * Add documentation about Packet Link mode + + * Add documentation about forcing TeleMini RF parameters to + known values. + + * Create a proxy server for Google Maps to re-enable map + images + + * Fix Java version info in all distributed jar files so that + applications will run with standard Mac OS X Java. + + * Replace JavaApplicationStub for Mac OS X so that + applications will run with Oracle Java. + + diff --git a/doc/release-notes.inc b/doc/release-notes.inc index 693699df..1183fd12 100644 --- a/doc/release-notes.inc +++ b/doc/release-notes.inc @@ -1,6 +1,10 @@ [appendix] == Release Notes :leveloffset: 2 + include::release-notes-1.8.7.raw[] + + <<<< + :leveloffset: 2 include::release-notes-1.8.6.raw[] <<<< diff --git a/doc/specs.inc b/doc/specs.inc index f09d6fc9..1b7ea74b 100644 --- a/doc/specs.inc +++ b/doc/specs.inc @@ -76,6 +76,15 @@ |1MB |- |3.7-12V + + |EasyMini v2.0 + |MS5607 30km (100k') + |- + |- + |- + |1MB + |- + |3.7-12V endif::easymini[] ifdef::telemega[] @@ -96,6 +105,15 @@ |8MB |40mW |3.7V + + |TeleMega v3.0 + |MS5607 30km (100k') + |MMA6555 102g + |uBlox Max-7Q + |MPU9250 + |8MB + |40mW + |3.7V endif::telemega[] ifdef::easymega[] diff --git a/doc/telegps-docinfo.xml b/doc/telegps-docinfo.xml index 5e347cfd..4d3533de 100644 --- a/doc/telegps-docinfo.xml +++ b/doc/telegps-docinfo.xml @@ -10,7 +10,7 @@ <email>keithp@keithp.com</email> </author> <copyright> - <year>2015</year> + <year>2018</year> <holder>Bdale Garbee and Keith Packard</holder> </copyright> <mediaobject> @@ -38,6 +38,14 @@ <revhistory> <?dbhtml filename="telegps-revhistory.html"?> <revision> + <revnumber>1.8.7</revnumber> + <date>08 Oct 2018</date> + <revremark> + Fix TeleBT v4.0 RF calibration to factory value when + reflashing. Fix map images. Fix Mac OS X support. + </revremark> + </revision> + <revision> <revnumber>1.8.3</revnumber> <date>11 Dec 2017</date> <revremark> diff --git a/doc/telemini.inc b/doc/telemini.inc index b40582a2..08893dfb 100644 --- a/doc/telemini.inc +++ b/doc/telemini.inc @@ -94,6 +94,56 @@ the left power switch wire. Hook a lead to either of the mounting holes for a ground connection. + === Using Packet Link Mode with TeleMini + + After TeleMini powers up, it will check to see if some + device is attempting to communicate with it using + Packet Link Mode. If so, it will switch to idle mode + and start communicating. To switch to flight mode, + reboot the device either over the radio link or by + powering it off and back on. + + If no ground station is attempting to communicate + using Packet Link Mode, TeleMini will enter pad mode + and prepare for flight. + + The sequence of operations to use Packet Link Mode + with TeleMini is: + + 1. Configure the ground station data rate, frequency + and callsign to match the TeleMini settings. + + 2. Start Packet Link Mode in the ground station by + selecting the desired operation (Safe Flight Data, + Configure Altimeter, Fire Igniter or Monitor + Idle). Select the TeleBT or TeleDongle device. The + red LED should begin flashing rapidly. + + 3. Turn on TeleMini. You should see the red LED flash + very rapidly during the initial communication burst, + but it should then slow down when the link is idle. + + Once TeleMini is in Idle mode, it will stay in that + mode until rebooted. That means you can stop one + Packet Link operation, wait a while and start another + Packet Link operation. + + === Forcing TeleMini radio parameters to known defaults + + If you don't know what the TeleMini frequency and + callsign settings are, you can temporarily force it + back to the original default values (frequency + 434.550MHz, callsign N0CALL) by connecting a wire + between hole 3 and hole 7 on the debug connector. Hole + 3 has the square pad around it, hole 7 is the one + nearest the MS5607 baro sensor, which is a rectangular + component with a metal cap that has two holes in it. + + Once TeleMini has been powered up with this wire + connected, the wire may be removed. The radio + parameters will stay set to these default values until + changed by the user or when the device is rebooted. + === TeleMini v1 TeleMini v1 is the earlier version of this product. It diff --git a/doc/usage.inc b/doc/usage.inc index d010f398..dd795bdd 100644 --- a/doc/usage.inc +++ b/doc/usage.inc @@ -323,3 +323,22 @@ different kind of battery to any of these will destroy the board. endif::telemega,easymega,telemetrum[] + + === Using Packet Link Mode + + All AltusMetrum flight computers that have a radio can + communicate with the ground station software for + configuration and other operations using the Packet + Link mode. This uses radio communication instead of a + USB cable. To set this up, the ground station software + must be configured to the correct data rate, frequency + and callsign. + + You can monitor Packet Link mode from TeleBT or + TeleDongle by watching the LEDs. Each time the device + transmits, the red LED will flash. When the link is + busy, or when the link is not working, the device will + transmit 10 times per second, so the LED will flash + rapidly. When the link is working and there is no data + to send, the link will flash once per second, and the + LED will flash more slowly. |