1.0 release

Author: pcbennion

README.md

@@ -1,87 +1,160 @@
 # NavGrid
 
-NavGrid is an all-in-one navigation system for Starbase.
+<img src="img/title.jpg" alt="NavGrid" width="300" height="300">
 
-NavGrid builds upon Collective's ISAN2 GPS system, adding a familiar visual
-interface to supplement ISAN's raw-numbers display.
+NavGrid is an all-in-one navigation system for Starbase. It builds upon Collective's ISAN2 GPS system, adding an easy-to follow visual interface that supplements ISAN's raw-numbers display.
 
-[NavGrid UI picture]
+It features 6 directional presets, up to 14 editable user-defined waypoints, and several navigational displays to help point you whichever direction you might be going.
 
-It features 6 directional presets, up to 14 editable user-defined waypoints,
-and a wide variety of optional displays to help point you whichever direction
-you might be going.
+It works while stationary and while flying at max speed.
 
-[Navgrid + NavP + ISAN Picture]
+You can set waypoints at your current location and at far off destinations.
 
-NavGrid is designed with the following audiences in mind:
-- Pilots who want to just choose a destination and fly to it, without needing
-to stare at numbers, without fiddling with transponder settings, and without
-puzzling over which way is "up".
-- Streamers who want to navigate without displaying their numbers on the
-screen.
-- Clans who want member to be able to easily navigate multiple company stations.
-- Ship designers who want to provide more navigational quality-of-life without
-losing compatibility with Starbase's most prevalent GPS system.
 
-[Navgrid in action; pointing at Origin 14]
 
-## Requirements and Features
+Coordinate displays are *totally optional*. If you don't want your coordinates on display (or if you just want purely visual navigation) you can hide all related displays on a memory chip with no loss in functionality.
 
-Performance: *0.8s* refresh time with max *3.0s* processing latency
+Best of all, it is fully compatible with most other projects that use ISAN, as long as they are compatible with ISAN's `speed` setting.
+
+**If you want to take NavGrid for a test drive *right now*, download and import my <a href=blueprints/NavGridDemoShip.fbe download>NavGrid Demo Ship</a> for a fully functional QUAD setup.**
+
+<img src="img/demo_2.jpg" alt="Navigating at home..." width="800" height="600">
+
+# Table of contents
+- [Features and Options](#features)
+- [Getting Started](#gettingstarted)
+- [Controls](#controls)
+- [Manual Installation](#install)
+
+<div id='features'></div>
+
+# Features and Options
+
+**Performance:** *0.8s* refresh time with max *3.0s* processing latency.
 
 **Core:**
-[Picture 3 nav recievers, 4 racks, and the required controls]
+
+- NavGrid display: visual ASCII display for easy directional navigation.
+- 6 Directional presets for general navigation (2 for each x, y, z axis).
+- 10 user-defined waypoints.
+- ISAN MONO.
 - Triplicate ISAN synchronization: 3 individual ISAN units operate on separate
 synchronized chips to provide maximum accuracy with zero performance loss.
 - Full support for any other ISAN addons you might be using, as long as they
-let you run with ISAN `speed` enabled.
-- Nav "Ball" display: visual ASCII display for easy directional navigation.
-- 6 Directional presets for general navigation (2 for each x, y, z axis)
-- 10 user-defined waypoints
+are compatible with ISAN's `speed` option.
+
+
+**(Optional) QUAD:**
 
-**(Optional) ISAN QUAD:**
-[Picture 9 more nav recievers]
++ Improved response while turning.
 + QUAD damage detection: QUAD mode has the same automatic damage detection as
-standard ISAN, with all three units entering MONO in unison if receivers are
+standard ISAN, with all three units entering MONO in unison if any nonessential receivers are
 damaged or destroyed.
-+ Significantly reduced jitter while turning.
 
-**(Optional) Expansion modules:**
-[Picture 1 memory card and 1 chip]
-+ 4 more user-defined waypoints
-+ Display navpoint coordinates and ship attitude
+**(Optional) Expansion module:**
+
++ 4 more user-defined waypoints.
++ Display navpoint coordinates and ship attitude.
 
 **(Optional) Use your own waypoint system:**
-[Picture 1 rack]
+
 + Replace NavGrid's navpoint management with your favorite waypoint system, as
 long as it uses ISAN coordinates.
++ Refer to the [euler_waypoint.yolol](optional/custom_waypoints/euler_waypoint.yolol) source code and the chip diagram in [Manual Installation](#install) for instructions.
+
+<img src="img/demo_1.jpg" alt="...or in the belt" width="800" height="600">
+
+<div id='gettingstarted'></div>
+
+# Getting Started
+
+### **1 - Remove your ISAN chip**
+
+Don't worry: NavGrid includes [another one](required/isan.yolol).
+
+If you are unfamiliar with ISAN, please refer to the [ISAN manual](isan.to/doc) for a really good explanation of how all this works.
+
+### **2 - Download the <a href=blueprints/NavGridV1-0.fbe download>NavGrid V1.0</a> blueprint and import it into your SSC.**
+
+[This reddit post](https://www.reddit.com/r/starbase/comments/p49nc1/tutorial_how_to_share_selfmade_blueprints_with/) has good directions for importing blueprints.
+
+### **3 - Load the NavGrid blueprint and delete any modules you don't want.**
+
+<img src="img/modules_core.jpg" alt="Core" width="270" height="200"> | <img src="img/modules_quad.jpg" alt="QUAD" width="270" height="200"> | <img src="img/modules_exp.jpg" alt="Expansion" width="270" height="200">
+
+*My recommendation:* Use Core + the Expansion, but not QUAD. MONO requires a little more patience (just like regular ISAN) but it is sufficient for 90% of situations.
+
+- If you are adding NavGrid to a ship in the SSC, select everything that's left and save as a submodule so you can import it into other blueprints.
+- If you are adding NavGrid outside the SSC, just buy the "ship". (Make sure there's nothing else in your hangar first or things will go flying)
+
+### **4 - Add the included receivers to your ship**
+(IMPORTANT: If you are using QUAD, use those receivers *instead* of the receivers in core.)
+
+This is the complicated step. You'll notice my receivers are in a specific formation:
+
+<img src="img/installation_axes.jpg" alt="The 'L'" width="800" height="600">
+
+NavGrid has three ISAN units: a main ISAN unit for getting coordinates, a `forward` ISAN unit for figuring out where you're pointed, and a `down` ISAN unit for figuring out your roll.
+
+For NavGrid to be accurate, it is very important that all three units form an `L` with `forward` being forward and `down` being down, kind of like your flight control unit. Distance between the units does not matter much; units that are far apart help reduce jitter while flying, but NavGrid works even if the Receivers are right next to each other. *All that really matters is that they are in line with each other as shown above - that is **very** important.*
+
+Once installed, make sure that your main receiver has a field named `a`, your forward receiver has a field named `e`, and your down receiver has a field named `i`.
+
+**Additional information for QUAD ISAN:** 
+
+Pretend that each group of four is a single unit; try not to mix them up or move them out of formation when you install them.
+
+The main ISAN receivers" have variables named A, B, C, and D. Receiver A has `SignalStrength` renamed to `a` and `TargetMessage` renamed to `at`. B has `b` and `bt` and so on.
+
+Following that pattern, the "forward" and "down" receivers continue the alphabet from there:
+- Forward: E, F, G, and H
+- Down: I, J, K, and L
+
+For maximum accuracy, each grouping of A/E/I, B/F/J, C/G/K, and D/H/L should form their own `L` shape as shown below. The recievers included in the blueprint are in the correct formation but you should always double-check after installation.
+
+<img src="img/installation_quad_2.jpg" alt="QUAD L" width="400" height="300"> | <img src="img/installation_quad_1.jpg" alt="QUAD Naming" width="400" height="300">
+
+### **5 - Add all chip racks and displays**
+
+Almost done! All you need to do now is attach the included racks and displays wherever works best for you.
+
+The big 3x3 display is best used while not actively flying, so it doesn't need to be in the cockpit.
+
+### **6 - Take it for a spin!**
+
+Once everything is installed, the NavGrid display should not be displaying any warnings if ISAN is working correctly. Try restarting ISAN if there are any errors. 
+
+If "Receiver Error" pops up it means you are out of ISAN range or one or more recievers can't be found. Check your receiver cables and try renaming their fields again.
+
+Once NavGrid is displaying its crosshair, set your waypoint to 4 and follow the dot. If your receivers are properly aligned, you should end up pointed at Eos with :Pit near 0 and :Hdg near +/-180
+
+<div id='controls'></div>
+
+# Controls
 
-## Installation
+### **Selecting navpoints:**
+Press nUp or nDn to change the selected navpoint.
 
-Installation is similar to ISAN2, but with more units. Please refer to the [ISAN
-manual](isan.to/doc) for a really good explanation of how to install, name, and
-operate each unit.
+### **Set current navpoint to the current coordinates:**
+Press nSet. Press again to overwrite if a navpoint already exists at this index. Presets cannot be overwritten.
 
-#### Chips and memory:
-[Picture mapping chip types to file names]
-[Picture of memory contents]
+### **Edit navpoint or set navpoint from coordinates:**
+Using the universal tool on the included displays, edit nName, nX, nY, and/or nZ as desired. Press nSave. Press again to confirm overwrite. Presets cannot be edited.
 
-#### Receivers:
-It is very important that receivers are installed in the correct "L" shape. If
-your axes are misaligned, your navigation will be misaligned.
+<img src="img/controls_grid.jpg" alt="The Grid" width="300" height="300"> | <img src="img/controls_eng_panel.jpg" alt="Engineering Panel" width="470" height="350">
 
-[Picture showing reciever axes]
+<div id='install'></div>
 
-By default, NavGrid assumes your recievers will be "forward" and "down" from
-your primary ISAN receiver(s). You can use "rear" and "up" receivers instead
-with a small code edit:
+# Manual Installation
 
-[Picture showing axis options]
+I highly recommend the blueprint-based installation in the [Getting Started](#gettingstarted) section. Copying multiple scripts by hand is much more tedius and error-prone.
 
-For quad setups, name location is also very important. Make sure corresponding
-receivers for each ISAN direction are in-axis with each other as shown here:
+If you're still here then I'll assume you know your way around a yolol chip:
 
-[Picture showing QUAD naming]
+1) Copy all `required` chips and any desired `optional` chips.
+    - The source files in git have full documentation complete with usage, required controls (if any), and additional installation directions. Chip installation is pretty simple compared to receiver installation, but if you don't read the docstrings you'll probably miss something!
+2) Set up your receivers in the `L` formation shown in the [Getting Started](#gettingstarted) section.
+    - Make sure each receiver has `SignalStrength` and `TargetMessage` renamed to the correct names, as shown in that section.
 
-#### Controls and operation:
-TODO
+My core chips are arranged as follows, in case you want to pull chips from the blueprint instead of copying:
+<img src="img/installation_rack.jpg" alt="QUAD Naming" width="800" height="600">

blueprints/NavGridV1-0.fbe

@@ -18,16 +18,17 @@ e*=e>0 e+=2*(:sy>A)*(e<5) IF e--<1 THEN m=at END :Attitude=m GOTO3
 
 
 
-
-
-
-
 // ------------------ This line is 70 chars long ------------------- >
 
 // extra_displays.yolol
 //     by StandPeter
 
 // ------------------ This line is 70 chars long ------------------- >
 
-// This optional chip creates easy displays for your current vehicle
-// attitude and the ISAN coordinates of your navpoint target.
+// This optional chip formats some of navgrid's internal  variables
+// into displays for extra information.
+
+// Atttude: Displays your vehicles current roll, pitch, and heading.
+
+// NavC: Displays the x, y, z coordinate of your current selected
+// navpoint.

blueprints/NavgridDemoShip.fbe

@@ -34,4 +34,6 @@ s=:sy err+=2*(err<9)*(:sy>"9") GOTO6-(err--<1) // euler_attitude.yolol
 // Heading is rotation along the ISAN Y axis (ie :Hdg=0 when you are
 // pointed directly into the belt) and Pitch is inclination along the
 // ISAN Y axis (ie :Pit=90 when you are pointed directly up toward the
-// top of the belt)
+// top of the belt)
+
+// Outputs are saved to :Pit, :Hdg, and :Rol

img/controls_eng_panel.jpg

@@ -2,7 +2,7 @@ o=90 p=180 u=40 v=50 d=10 h=0.5 ds="$" ns="" nd=0 t="9843" r=17 GOTO3
 :nPit=u*n3^3+v*n3 :nHdg=(1-2*(n1>0))*(-u*i^3-v*i+o) :nDist=nd
 s0=:sy%4 x=1*nd n1=:nX-:x n2=:nZ-:z n3=:nY-:y nd=SQRT(n1^2+n2^2+n3^2)
 :nStat="" x=1*nd n1/=nd n2/=nd n3/=nd nd=nd/1000*1000  //euler_navp by
-i=n2/SQRT(1-n3^2) x=:sy%4 GOTO5-(3-11*(ns!=:nStr))*(x!=s0)//StandPeter
+i=n2/SQRT(1-n3^2) x=:sy%4 GOTO5-(3-12*(ns!=:nStr))*(x!=s0)//StandPeter
 s0=:sy err+=2*(err<9)*(:sy>"9") x=6-(err--<1) GOTOx+(14-x)*(ns!=:nStr)
 s-- s*=s>0 p1="X+:\nPrograde0" p2="X-:\nRetrograde1" p3="Z+:\nRadial2"
 s*=s<7 p4="Z-:\nAnti-radial3" p5="Y+:\nNormal4" p6="Y-:\nAnti-normal5"
@@ -28,7 +28,14 @@ ss="[  ERROR  ]" :nStat=ss nn="Bad Format" :nName=nn GOTO13  //NavGrid
 // ADVANCED CHIP REQUIRED
 
 // Computes the Euler Angles of your target navpoint to find its
-// alignment related to your current position.
+// alignment relative to your current position.
 
-// Whenever a new navpoint is loaded into nStr by navp.yolol, this
-// chip decodes it into usable coordinates.
+// Euler outputs are saved to :nPit, :nHdg, and :nDist
+
+// Whenever a new navpoint is loaded into :nStr by navp.yolol, this
+// chip decodes it into usable coordinates.
+
+// Once loaded, navpoint attributes are saved to :nName, :nX, :nY, :nZ
+
+// Navpoint status messages (such as loading, no waypoint, etc) are
+// saved to :nDist

img/controls_grid.jpg

@@ -29,4 +29,6 @@ s=:sy err+=2*(err<9)*(:sy>"9") GOTO6-(err--<1) // euler_relative.yolol
 
 // Subtracts absolute attitude from navpoint alignment, and rotates
 // the result by your current roll to determine the relative pitch and
-// heading to your navpoint target.
+// heading to your navpoint target.
+
+// Outputs are saved to :tPit and :tHdg

img/demo_1.jpg

@@ -1,6 +1,6 @@
 A=1000 n=1000 pr=0 sp=1 dv=(9.6+2.4*pr)*n so=1-sp o=160000 e=8*o c=""
 z="origin_" mr=z+"north" br=z+"south" cr=z+"east" z+="west" sm="\nS: "
-u=e*3/13 l=2*o mm=l*13/19 k=e*3/19 :sy=0 q=15 x/=so sm=c ss=c
+u=e*3/13 l=2*o mm=l*13/19 k=e*3/19 :sy=4 q=15 x/=so sm=c ss=c
 rr="ISAN2 :_\n     " xm="\nX: " ym="\nY: " zm="\nZ: " nn=l*13/3
 ej=17*sp h="Q" pj=15-pr b=0.5 p=1000000 :at=mr :bt=br :ct=cr :dt=z x=0
 t=(p-:a)^2 i=(p-:b)^2 g=(p-:c)^2 f=(p-:d)^2 :sy=jj++%4+4/(:sy>3) gotoq
@@ -26,11 +26,10 @@ st=:_!=c :_=rr+"\n\n   ISAN2\n  OFFLINE" goto 20*st   // by StandPeter
 // MODIFIED BY STANDPETER FOR USE BY NAVGRID:
 // - Set speed mode to 1.
 // - Save xx, yy, zz to :x, :y, :z respectively.
-// - line 3: update variable initialization to account for other
-// changes.
 // - lines 6-10: Save a synchronization heartbeat to :sy to help keep
-// all three ISAN chips in sync, so they will all take readings from
-// the same transmitter at the same time and will all move to MONO
-// once any of them switch to MONO.
-// - lines 6-13: Introduce power operations to save space. Move the
-// catch for basic chip syntax errors to line 13.
+// all three ISAN chips in sync so they will all take readings from
+// the same transmitter at the same time. This is necessary for
+// Navgrid to work while moving. :sy is also used for damage detection
+// and for displaying error messages.
+// - lines 6-13: Use power operations where appropriate to make room
+// for the :sy heartbeat

img/demo_2.jpg

@@ -34,7 +34,7 @@ a=:np17 b=:np18 c=:np19 d=:np20 v=a+b+c+d-w-a-b-c-d GOTO2
 // - Up to 14 editable user-defined navpoints. Navpoints can be
 //   selected, set, and edited using the controls below
 
-// Controls:
+// Required Controls:
 // - nUp, nDn: Any button; ButtonStyle=1. Increase or decrease the
 // current navpoint index
 // - nSet: Any button; ButtonStyle=1. Set the selected navpoint to the