add JLC parts ordering and buying guide

flake.nix

@@ -14,6 +14,26 @@
       };
     in
     {
+      packages.default = pkgs.stdenv.mkDerivation {
+        pname = "naxgcc-doc";
+        version = "1.0.0";
+
+        nativeBuildInputs = builtins.attrValues {
+          inherit (pkgs) mdbook mdbook-katex;
+        };
+
+        src = self;
+        buildPhase = ''
+          mdbook build
+        '';
+
+        installPhase = ''
+          mkdir -p $out
+
+          cp -r book/* $out
+        '';
+      };
+
       devShells.default = pkgs.mkShell {
         nativeBuildInputs = builtins.attrValues {
           inherit (pkgs) mdbook mdbook-katex;

src/buying-guide.md

@@ -1 +1,85 @@
 # NaxGCC Buying Guide
+
+So you want to buy a NaxGCC, but you may not know what to look for, and you may not know how experienced the seller is at making them. Since the NaxGCC is very similar in assembly to the PhobGCC, generally speaking, if you know a seller is experienced at assembling PhobGCCs, you can probably expect them to make a good NaxGCC as well.
+
+However, it is still important to know what to look for, especially if you're buying a used controller, in which case you may not know who assembled it at all.
+
+This guide aims to show you what to check for, ideally before you buy. If buying in-person, ask the seller to take it apart to show you.
+
+Also note that a Phob 2.0 can be turned into a NaxGCC, and in this case special considerations apply.
+
+## Easy Checks
+
+This section is for things that are simple to verify without technical knowledge: whether it works, and important part selection.
+
+### Board Version
+
+As of writing, the latest and only version of the NaxGCC board is `1.0.0`. If you see a version number other than this, it could be an unofficial fork with changes that may or may not be beneficial. Ask the seller about it.
+
+#### Conversion Boards
+
+If the controller is a Phob 2.0 that has been converted to a NaxGCC, ensure that the seller made sufficient modifications to the controller shell to allow a micro USB cable to connect to the Phob board during play. Otherwise, you won't be able to actually connect the controller to your console.
+
+### Functionality
+
+Obviously, the controller should work. To verify functionality, it is recommended that you use [Smashscope](https://goomwave.com/2020/06/28/smashscope-guide/). Have a look at the [Getting Started](./configuration.md#getting-started) section of our configuration guide for more information on how to set it up.
+
+The `L` & `R` triggers should not depress fully as with an OEM controller, but instead feel similar to the face buttons, with a short travel distance. They should register at full `255` values when pressed. Rumble should function as well (assuming a rumble motor is installed). You can verify this by pressing `Z` on the Controller Test screen in Smashscope.
+
+The sticks should not be very noisy or jittery when held off-center, but jitter between two adjacent values is acceptable. Notches should have repeatable coordinates when entered from the same direction, though they may have different coordinates if entered differently (clockwise, counterclockwise, straight from the center).
+
+The controller should be set up so that it doesn’t have snapback. You can test this in game, but ideally you can run Smashscope and make use of its oscilloscope. Consult the [Beginning Calibration](./configuration.md#beginning-calibration) section of our configuration guide for more information on what it's supposed to look like.
+
+### Stickbox
+
+The stickboxes which contain the stick mechanism should be T3, which are entirely white plastic and mounted with two screws on the underside of each.
+
+T1/T2 stickboxes, which have metal frames around plastic innards, are far more prone to wear and becoming loose. Additionally, they are soldered down, making them difficult to replace. This effectively limits the lifespan of a NaxGCC.
+
+### C-Stick Board
+
+The C-Stick board should be a NaxGCC one with magnets, rather than an OEM C-Stick board with potentiometers. A Phob 2.0 daughter board can be used, and Phob 2.0.5 daughter boards are guaranteed to behave the exact same as a NaxGCC one.
+
+The NaxGCC will _not_ function with an OEM C-Stick board, or an earlier-generation Phob daughter board.
+
+### USB Cable
+
+If the seller included a USB-C cable, ensure that it stays in place when inserted, doesn't fall out easily, and doesn't wobble. The Nintendo Switch is very particular when it comes to having a stable connection, and a loose cable can cause the controller to disconnect during play.
+
+Ideally, you should be able to hang the controller from the cable, give it a good few shakes (not like Hercules, however), and it should not come loose. There should be some force required to remove the cable, and you should feel a click when inserting it. When wiggling the cable side-to-side, the controller should not disconnect (test this on an actual Nintendo Switch if possible).
+
+## Intermediate Checks
+
+Here is where we begin evaluating the quality of the work.
+
+### Soldering Workmanship
+
+#### Shorts
+
+There must be no connections made between pads that are close together. You should be able to see green completely separating the solder.
+
+#### Solder Joint Shininess
+
+It is commonly believed that solder joints are supposed to be shiny, but that mainly applies to leaded solder (Sn63 or Sn60), not lead-free solder (such as SAC305). Most commercial products these days use SAC305 or similar due to regulations, but Sn63 is still often preferred by hobbyists for its ease of use.
+
+Ask your vendor what kind of solder the NaxGCC you are evaluating was made with before judging the joint quality by how shiny they are.
+
+#### Solder Bonding
+
+All solder joints should have the solder clearly sticking to both the component and the board in order to make a strong physical and electrical connection.
+
+#### Solder Quantity
+
+The entire pad on the board should be wet out with solder, but there ideally should not be enough solder to form a convex ball.
+
+<img src="./assets/solder.png" style="display: block; margin-left: auto; margin-right: auto;" />
+
+This is an example of a solder joint that has poor contact with the board and caused undesirable stick behavior.
+
+### Physical Workmanship
+
+#### Stickbox Magnets
+
+<img src="./assets/stickbox.png" style="display: block; margin-left: auto; margin-right: auto;" />
+
+The magnet mounts on the stickbox should be firmly glued in place, and not come loose easily. A good way to test this is to use another magnet of the same strength and see if it can pull the magnet mount away from the stickbox. If it doesn't come loose, it's a good indicator that your controller will be able to sustain one or the other fall to the ground without the magnet mounts falling off.

src/configuration.md

@@ -278,6 +278,8 @@ Cycles the input consistency setting through its three modes and displays which
 
 For more information about the different input consistency modes, consult the [Input Consistency Mode](./input-consistency.md#input-consistency-modes) list.
 
+> **NOTE:** This setting will only become active upon unplugging and replugging the controller.
+
 ---
 
 ## Display Values

src/input-consistency.md

@@ -2,6 +2,8 @@
 
 This is a rather technical document about USB polling, input latency, and the issues that arise with input consistency. If you only care about the NaxGCC's solutions to this problem, and not the background knowledge, you can skip ahead to the [Input Consistency Modes](#input-consistency-modes) section.
 
+> **NOTE:** "Input consistency" and "input integrity" are used interchangeably in this document.
+
 ## General Info
 
 The vast majority of human interface devices (HIDs) transmit their states over USB using a technique known as "polling". Essentially, these devices (clients) advertise themselves as supporting a certain polling interval/frequency to whatever device they're attached to (hosts). The host then polls the client at the desired frequency, or at a lower one (= not as often, = more slowly) if the host doesn't support the client's desired frequency.
@@ -10,11 +12,11 @@ The Nintendo Switch supports polling USB devices at up to $125\mathrm{Hz}$, or o
 
 The reason it's "up to 3 times" and not "3 times, period" is because the USB polling and the game's frame draws are not in sync. Otherwise, a polling interval of $\approx16.66\mathrm{ms}$ would be perfectly sufficient, provided the host polls the adapter right before the frame is supposed to be drawn$^1$. Due to technical reasons, this is not possible however, so we are stuck with two asynchronous intervals: Polling & frame draws.
 
-$^1$even if the host didn't poll the adapter right before the frame is drawn, it would still be fine, because as long as the polling interval is a multiple of the frame draw time, at least input _integrity_ would be guaranteed, even if _latency_ could still be variable depending on when your device was plugged in
+$^1$even if the host didn't poll the adapter right before the frame is drawn, it would still be fine, because as long as the polling interval is a divisor of the frame draw time, at least input _integrity_ would be guaranteed, even if _latency_ could still be variable depending on when your device was plugged in
 
 ## Input Integrity
 
-Now, what does this mean for your input integrity? Essentially, in a system where polling intervals are _not_ multiples of each other, the time window in which your inputs are _guaranteed_ to come out on the frame you'd expect them to is equal to $T_f-T_p$ where $T_f$ is the time it takes to draw a frame ($\approx16.66\mathrm{ms}$) and $T_p$ is the polling interval ($8\mathrm{ms}$). So, on the Nintendo Switch, where USB polling is locked $8\mathrm{ms}$ and frame time of Smash Ultimate is $\approx16.66\mathrm{ms}$, our window of time during which inputs are _guaranteed_ to come out on the _expected_ frame is $16.\overline{6}\mathrm{ms} - 8\mathrm{ms} = 8.\overline{6}\mathrm{ms}$
+Now, what does this mean for your input integrity? Essentially, in a system where polling intervals are _not_ multiples/divisors of each other, the time window in which your inputs are _guaranteed_ to come out on the frame you'd expect them to is equal to $T_f-T_p$ where $T_f$ is the time it takes to draw a frame ($\approx16.66\mathrm{ms}$) and $T_p$ is the polling interval ($8\mathrm{ms}$). So, on the Nintendo Switch, where USB polling is locked $8\mathrm{ms}$ and frame time of Smash Ultimate is $\approx16.66\mathrm{ms}$, our window of time during which inputs are _guaranteed_ to come out on the _expected_ frame is $16.\overline{6}\mathrm{ms} - 8\mathrm{ms} = 8.\overline{6}\mathrm{ms}$
 
 This then means that during the first $\approx8.66\mathrm{ms}$ of a "frame capture window", your input is guaranteed to come out on the frame you'd expect (the one whose frame capture window is currently open). For any input, the probability $p(n)$ that your input will arrive at the expected frame, for any $n$ that is the time elapsed (in ms) since the start of the frame capture window, is $p(n) = \frac{T_f - n}{T_p}$. As you can see, for $n \leq T_f - T_p, p(n) \geq 1 \rightarrow p(n) = 1$, and for $n \gt T_f - T_p, p(n) \lt 1$.
 
@@ -63,14 +65,18 @@ The NaxGCC features three separate input consistency modes, which can be [cycled
 
 ### Regular Mode
 
-In regular mode, the NaxGCC will not attempt to modify the polling rate of the controller, and will instead send the controller's state to the console as soon as it is requested. This is the same behavior as the vast majority of other USB controllers and adapters when connected to the Nintendo Switch. This mode is not recommended for competitive play, as it carries a $\approx24.01\%$ chance of your inputs being misinterpreted.
+In regular mode, the NaxGCC will not attempt to modify the polling rate of the controller, and will instead send the controller's state to the console as soon as it is requested. This is the same behavior as the vast majority of other USB controllers and adapters when connected to the Nintendo Switch. This mode is not recommended for competitive play, as it carries a $\approx24.01\%$ chance of your inputs being misinterpreted (see [Input Integrity](#input-integrity) for details).
 
 ### Consistency Mode
 
-In consistency mode, the NaxGCC introduces a variable delay in order to wait responding to a poll request from the console until exactly $8.\overline{3}\mathrm{ms}$ (half a frame) have elapsed. This ensures that the controller is polled exactly twice as often as the game updates and (nearly) eliminates the chance of your inputs being misinterpreted. This is the recommended mode for competitive play, and is the default mode for the NaxGCC.
+In consistency mode, the NaxGCC introduces a variable delay in order to wait responding to a poll request from the console until exactly $8.\overline{3}\mathrm{ms}$ (half a frame) have elapsed since the last status update. This ensures that the controller is polled exactly twice as often as the game updates and (nearly) eliminates the chance of your inputs being misinterpreted. This is the recommended mode for competitive play, and is the default mode for the NaxGCC.
+
+> **NOTE:** While this is not exactly in-spec behavior for a USB device, it is still within the realm of what is possible with USB, and has been extensively tested to ensure that it does not cause any issues with the console.
 
 ### "Super Hack" Mode
 
-In "super hack" mode, the NaxGCC avoids responding to the console's poll requests until the controller state has changed, _and_ at least $8.\overline{3}\mathrm{ms}$ have elapsed since the last poll request. This ensures that, for inputs made more than $8.\overline{3}\mathrm{ms}$ apart, the latency is minimized, since the state is immediately dispatched to, and interpreted by, the console, at a slight cost to input integrity for inputs made less than $8.\overline{3}\mathrm{ms}$ apart. This mode is currently experimental, as it is still undergoing extensive testing, and is currently **not** recommended for competitive play.
+In "super hack" mode, the NaxGCC avoids responding to the console's poll requests until the controller state has changed, _and_ at least $8.\overline{3}\mathrm{ms}$ have elapsed since the last poll request. This ensures that, for inputs made more than $8.\overline{3}\mathrm{ms}$ apart, the latency is minimized, since the state is immediately dispatched to, and interpreted by, the console, at a slight cost to input integrity for inputs made less than $8.\overline{3}\mathrm{ms}$ apart.
 
-**Note:** "Super Hack" does not refer to this being a hack that is super, but rather something that is super hacky, since this pretty much out of spec behavior for a USB device.
+> **WARNING:** This mode is currently experimental, as it is still undergoing extensive testing, and is currently **not** recommended for tournament play.
+
+> **NOTE:** "Super Hack" does not refer to this being a hack that is super, but rather something that is super hacky, since this pretty much out of spec behavior for a USB device.

src/jlcpcb-parts-ordering.md

@@ -1 +1,93 @@
 # JLCPCB Parts Ordering
+
+This is an illustrated guide to ordering NaxGCC PCBs via the JLCPCB Board House.
+
+## JLC Ordering Process Overview
+
+This is very important, or else you will get nonfunctional boards.
+
+1. Preorder the SMD components that are in limited supply, as listed below.
+   - These are not stocked by JLC but they are stocked by distributors; JLC will order them and keep them in your name until you order boards that need them.
+2. Once **ALL OF THE PARTS** come in, only then order boards with assembly.
+   - You may need to wait a week or more.
+   - Do not order boards before you receive notification that ALL of your parts are available.
+   - If you order boards before parts are available, then they will be assembled without the parts and they will not function.
+3. Wait for your boards to come in.
+
+## Pre-ordering SMD components
+
+Since the NaxGCC board is fully integrated, all of the non-GCC components are soldered onto the board at the board house. Some of these may be out of stock, and as such need to be pre-ordered before you place a board order. Pre-ordered components take on average 2 weeks to arrive at the JLCPCB warehouse after you pay for them. If a component takes longer, you can contact JLCPCB support for a more accurate timeframe of arrival.
+
+The following parts usually have low stock and pre-ordering them is advised:
+
+> **NOTE:** These part quantities are for a single NaxGCC board. You need to multiply them by the number of boards you plan to order.
+
+> **NOTE:** You can only order PCBs in quantities of 5, 10, 15, 20, 25, 30, 50, or more. Do not order SMD components for amounts other than these or you will either have unused extra parts or unpopulated PCBs later.
+
+- [1x RP2040](https://jlcpcb.com/partdetail/RaspberryPi-RP2040/C2040)
+- [1x Winbond NOR Flash Chip](https://jlcpcb.com/partdetail/WinbondElec-W25Q128JVSIQ/C97521)$^1$
+- [4x DRV5055 SMD Hall Sensor](https://jlcpcb.com/partdetail/TexasInstruments-DRV5055A3QDBZR/C266128)
+- [2x MCP2302 ADC](https://jlcpcb.com/partdetail/MicrochipTech-MCP3202_CISN/C56997)
+- [1x Crystal Oscillator](https://jlcpcb.com/partdetail/390662-TAXM12M4RKDCDT2T/C403945)$^2$
+
+$^1$if you're planning on swapping out the Winbond chip for a different one, note that the serial number reported by the NaxGCC upon plug-in may no longer be unique
+
+$^2$you need 1 more cystal oscillator per order you plan to place regardless of how many boards are in the order
+
+Once you've clicked on each link and added the quantities you need into your cart, click the cart icon in the top right, go to the "Parts Manager Tab", to the "Order Parts" subtab, to the "Cart" subtab as follows:
+
+<img src="./assets/jlc-order.png" style="display: block; margin-left: auto; margin-right: auto;" />
+
+This is where you double-check the part quantities you've selected and make sure that they're all checked, even if in stock. Once you checkout, JLC will attempt to purchase those parts for you at the quoted price. If they end up costing more, they'll email you about supplementing the cost, and if they end up costing less, you will be refunded the difference. You can check the status of part orders in the "Parts Order History" subtab.
+
+Some of the parts may be in stock and be available immediately. You must wait until **ALL PARTS** are available before proceeding. This may take one or two weeks.
+
+## Purchasing the NaxGCC board from JLCPCB
+
+> **NOTE:** Once your pre-ordered SMD Components have come in (report as "Complete" in the parts order history), you may proceed to ordering boards. If they are not in, the parts will not be present on your board, and your board will not be functional.
+
+Download the files available in the [NaxGCC-HW git repo](https://git.naxdy.org/NaxdyOrg/NaxGCC-HW/releases) in the releases section as shown below:
+
+<img src="./assets/naxgcc-hw-download.png" style="display: block; margin-left: auto; margin-right: auto;" />
+
+Make sure to redownload the latest even if you already downloaded it in the past, as occasionally we make changes to the components to account for stock shortages or changes.
+
+Once you've extracted the files from the `.zip`, you should have three files:
+
+- NaxGCC_vX.X.X.zip (the gerber files)
+- NaxGCC_vX.X.X_bom.csv (the bill of materials)
+- NaxGCC_vX.X.X_top-pos.csv (the component placement file)
+
+Click "Order Now" on JLCPCB, make sure you are set to "Standard PCB/PCBA" tab, click "Add Gerber File", and upload the `NaxGCC_vX.X.X.zip`. Once the files are uploaded, you should see the board process and then load in as shown below:
+
+<img src="./assets/jlc-gerber.png" style="display: block; margin-left: auto; margin-right: auto;" />
+
+Once you've checked that the size is set to `96.07x125.5mm`, you can progress with configuring it. The recommended settings are the defaults, setting your board quantity, setting "Different Design" to 2, and setting the Surface Finish to ENIG, as seen below:
+
+<img src="./assets/jlc-config.png" style="display: block; margin-left: auto; margin-right: auto;" />
+
+Scroll down to PCB Assembly and toggle it on the right. Select Standard PCBA Type (Not available for large orders or colors), the top side, and confirm parts placement as seen below.
+
+> **NOTE:** For large orders such as more than 50 boards or different colors, Standard Assembly is required. This attaches removable rails to the PCB at a significant extra cost.
+
+> **NOTE:** If arranging group buys or purchasing in large quantities, we strongly suggest using Standard PCBA so DOA boards are less likely.
+
+<img src="./assets/jlc-assembly-config.png" style="display: block; margin-left: auto; margin-right: auto;" />
+
+Click "Confirm" and then upload the `NaxGCC_vX.X.X_bom.csv` to the left and and the `NaxGCC_vX.X.X_top-pos.csv` to the right. Set the usage description to Research/Education/DIY $\to$ DIY HS Code and click "Next". The text at the top of the next screen should look like the following with all 25 confirmed.
+
+<img src="./assets/jlc-parts-confirmation.png" style="display: block; margin-left: auto; margin-right: auto;" />
+
+The important part is that it should read `26` parts confirmed. Don't worry about the `11` parts not selected, as these are parts that will be added afterwards in the assembly process (stickbox assemblies, face buttons, etc.).
+
+After clicking "Next", you'll be presented with a view of the parts on the board. If this screen is corrupted, that's okay. The files are known good and this is just the website bugging out. You want to make sure there are **no red boxes anywhere** as those indicate missing components. Ideally, the top view should look something like this:
+
+<img src="./assets/jlc-assembly-topview.png" style="display: block; margin-left: auto; margin-right: auto;" />
+
+At this stage, don't worry if some components are in the right position, but rotated incorrectly. This should be corrected by JLCPCB later in the process, and this is why we selected "Confirm Parts Placement" earlier in the process, so you'll get to inspect the corrected parts placement before the order is put into production. You can then click "Save To Cart" and pay for your boards.
+
+Later on, you will get a notification that the parts placement is ready for review. The corrected parts placement should look something like this:
+
+<img src="./assets/jlc-corrected-placement.png" style="display: block; margin-left: auto; margin-right: auto;" />
+
+If everything looks good, go ahead and confirm the parts placement. Your boards will then be put into production and shipped to you as soon as they're done.

src/update-firmware.md

@@ -18,6 +18,8 @@ If you already have a controller with firmware on it, updating is easy. Simply p
 >
 > Minor firmware updates (e.g. `1.0.x` to `1.1.x`) and fix updates (e.g. `1.0.0` to `1.0.1`) will not cause your configuration to be reset, and you can safely update without having to recalibrate.
 
+> **NOTE:** If holding the `A+X+Y` buttons doesn't work, e.g. because the connection was interrupted during the last flashing of the firmware, and the controller is stuck in a non-functional state, you must take it apart and press the `BOOTSEL` switch on the controller board itself. This is a small button located near the center of the board. Hold this button down while plugging in the controller to your computer, and it will show up as a mass-storage device. You can then drag & drop the firmware binary onto it.
+
 ## Downgrading your firmware
 
 If you ever need to downgrade your firmware, the process is the same as updating. Simply plug in your NaxGCC to your computer while keeping the `A+X+Y` buttons held. The controller will show up as a mass-storage device, similar to when you first plugged it in. Drag & drop the old firmware binary onto the device, and you're done!