From db61e97df544f4900b734f3d297fc6b28861f5f8 Mon Sep 17 00:00:00 2001 From: Gabe Venberg Date: Sun, 23 Feb 2025 21:03:00 +0100 Subject: [PATCH] added paged out articles. --- .envrc | 1 + .gitignore | 4 + flake.nix | 24 ++ paged-out!/nixos-easy-host/.gitignore | 1 + paged-out!/nixos-easy-host/main.typ | 114 ++++++++++ paged-out!/nixos-easy-host/template.typ | 36 +++ paged-out!/stop-using-trrs/.gitignore | 1 + paged-out!/stop-using-trrs/main.typ | 73 ++++++ paged-out!/stop-using-trrs/template.typ | 36 +++ paged-out!/stop-using-trrs/trrs.svg | 213 ++++++++++++++++++ .../trrs_fully_plugged_in_5v_sleeve.svg | 160 +++++++++++++ .../trrs_fully_plugged_in_5v_tip.svg | 160 +++++++++++++ .../trrs_partially_plugged_in_5v_sleeve.svg | 160 +++++++++++++ .../trrs_partially_plugged_in_5v_tip.svg | 160 +++++++++++++ paged-out!/typst-template/.gitignore | 1 + paged-out!/typst-template/main.typ | 7 + paged-out!/typst-template/template.typ | 36 +++ 17 files changed, 1187 insertions(+) create mode 100644 .envrc create mode 100644 .gitignore create mode 100644 flake.nix create mode 100644 paged-out!/nixos-easy-host/.gitignore create mode 100644 paged-out!/nixos-easy-host/main.typ create mode 100644 paged-out!/nixos-easy-host/template.typ create mode 100644 paged-out!/stop-using-trrs/.gitignore create mode 100644 paged-out!/stop-using-trrs/main.typ create mode 100644 paged-out!/stop-using-trrs/template.typ create mode 100644 paged-out!/stop-using-trrs/trrs.svg create mode 100644 paged-out!/stop-using-trrs/trrs_fully_plugged_in_5v_sleeve.svg create mode 100644 paged-out!/stop-using-trrs/trrs_fully_plugged_in_5v_tip.svg create mode 100644 paged-out!/stop-using-trrs/trrs_partially_plugged_in_5v_sleeve.svg create mode 100644 paged-out!/stop-using-trrs/trrs_partially_plugged_in_5v_tip.svg create mode 100644 paged-out!/typst-template/.gitignore create mode 100644 paged-out!/typst-template/main.typ create mode 100644 paged-out!/typst-template/template.typ diff --git a/.envrc b/.envrc new file mode 100644 index 0000000..3550a30 --- /dev/null +++ b/.envrc @@ -0,0 +1 @@ +use flake diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..79abec3 --- /dev/null +++ b/.gitignore @@ -0,0 +1,4 @@ +# direnv +.direnv + +*.pdf diff --git a/flake.nix b/flake.nix new file mode 100644 index 0000000..34660a9 --- /dev/null +++ b/flake.nix @@ -0,0 +1,24 @@ +{ + description = "A very basic flake"; + + inputs = { + nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable"; + flake-utils.url = "github:numtide/flake-utils"; + }; + + outputs = { + self, + nixpkgs, + flake-utils, + }: + flake-utils.lib.eachDefaultSystem (system: let + pkgs = import nixpkgs {inherit system;}; + in + with pkgs; { + devShells.default = mkShell { + buildInputs = [ + typst + ]; + }; + }); +} diff --git a/paged-out!/nixos-easy-host/.gitignore b/paged-out!/nixos-easy-host/.gitignore new file mode 100644 index 0000000..a136337 --- /dev/null +++ b/paged-out!/nixos-easy-host/.gitignore @@ -0,0 +1 @@ +*.pdf diff --git a/paged-out!/nixos-easy-host/main.typ b/paged-out!/nixos-easy-host/main.typ new file mode 100644 index 0000000..6e31caf --- /dev/null +++ b/paged-out!/nixos-easy-host/main.typ @@ -0,0 +1,114 @@ +#import "template.typ": article + +#show: article.with( + title: [Running non Nixpkgs services on NixOS, the lazy way], + authors: "Gabe Venberg", + date: datetime(year: 2024, month: 12, day: 04), + fontsize: 12pt +) + +#show heading.where(level: 2): it => text(size: 12pt, it.body + [:]) + +NixOS is really nice for self hosting. +Anything that has a NixOS module can be hosted in a few lines of nix code. +But what if the service we want to host doesn't come with a NixOS module written for us already in Nixpkgs? +This is where NixOS can be a little hard, as a guide on setting up a service in Debian or Arch will rarely work on NixOS. +Of course, the 'nix way' would be to write your own package and module for it, but that can be a daunting task. +Here are some 'escape hatches' to host some of the simpler services without having to write your own Nix package or module. + +#set rect( + inset: 8pt, + fill: rgb("e4e5ea"), + width: 100%, +) + +#grid(columns: (1fr, 2fr), gutter: 5mm, + [ + == Nginx + If the application is a simple static website, containing just HTML and JS, + the `nginx` module on NixOS provides us with a way to manage virtual hosts complete with https. + Shown is how I host my Hugo generated blog. + ], + rect[ + ```nix + { config, ... }: { + services.nginx.virtualHosts."gabevenberg.com" = { + enableACME = true; + forceSSL = true; + root = "/var/www/gabevenberg.com"; + }; + security.acme = { + acceptTerms = true; + defaults.email = "myname@example.com"; + }; + networking.firewall.allowedTCPPorts = [443 80]; + } + ``` + ], + grid.cell( + colspan: 2, + [ + The complete list of options for virtual hosts can be found here:\ + #link("https://nixos.org/manual/nixos/stable/options#opt-services.nginx.virtualHosts") + ], + ), + + [ + == Docker + If the service publishes a Docker image, one can just run that on NixOS. + Here's how I host a game server using a premade docker container. + Things get a bit more complicated with docker-compose, + but one can use #link("https://github.com/aksiksi/compose2nix") to translate a docker-compose.yaml file into a nix file much like the one shown. + ], + rect[ + ```nix + { config, ... }: { + virtualisation.oci-containers = { + backend = "docker"; + containers.factorio = { + image = "factoriotools/factorio:stable"; + volumes = ["/storage/factorio:/factorio"]; + hostname = "factorio"; + ports = ["34197:34197/tcp"]; + environment = {UPDATE_MODS_ON_START = "true";}; + }; + }; + virtualisation.docker.enable = true; + } + ``` + ], + grid.cell( + colspan: 2, + [ + There are, of course, more options for the oci-containers module, found at:\ + #link("https://nixos.org/manual/nixos/stable/options#opt-virtualisation.oci-containers.containers") + ], + ), + + [ + == Systemd + Finally, if the service is composed of a single static binary, NixOS makes it really easy to write Systemd services. + (I've used a package in Nixpkgs here, + but you could just as easily point the Systemd service to a binary you threw in `/opt/` or somewhere.) + ], + rect[ + ```nix + { config, ... }: { + systemd.services.miniserve = { + wantedBy = ["multi-user.target"]; + after = ["network.target"]; + description = "A directory miniserve instance"; + environment = {MINISERVE_ENABLE_TAR_GZ="true";} + serviceConfig.ExecStart = "${pkgs.miniserve}/bin/miniserve -i 127.0.0.1 -- /storage/miniserve" + }; + } + + ``` + ], + grid.cell( + colspan: 2, + [ + And like the last 2 times, the complete list of options for Systemd service can be found here:\ + #link("https://nixos.org/manual/nixos/stable/options.html#opt-systemd.services") + ], + )) diff --git a/paged-out!/nixos-easy-host/template.typ b/paged-out!/nixos-easy-host/template.typ new file mode 100644 index 0000000..5d3d87b --- /dev/null +++ b/paged-out!/nixos-easy-host/template.typ @@ -0,0 +1,36 @@ +#let article( + title: none, + authors: (), + date: datetime.today(), + margin: (x: 1mm, y: 1mm), + fontsize: 12pt, + doc, +) = { + //setup page size. Margin can be small because Paged Out! includes its own margins. + set page(width: 182mm, height: 253mm, margin: margin) + + //blue, web-style links. + show link: it => { + set text(blue) + underline(it) + } + + //Lets us fit a bit more text on the page without looking too cramped. + set text(size: fontsize) + set par(leading: 4pt, justify: true) + + //setup document metadata. (no clue if its useful to the Paged Out! pipeline, but just in case) + set document( + title: title, + author: authors, + date: date, + ) + + //setup top level headings. We leave styling the subheadings to the user. + show heading.where(level: 1): set text(size: 16pt) + + //render a title if one is provided. + if title != none { [= #title] } + + doc +} diff --git a/paged-out!/stop-using-trrs/.gitignore b/paged-out!/stop-using-trrs/.gitignore new file mode 100644 index 0000000..a136337 --- /dev/null +++ b/paged-out!/stop-using-trrs/.gitignore @@ -0,0 +1 @@ +*.pdf diff --git a/paged-out!/stop-using-trrs/main.typ b/paged-out!/stop-using-trrs/main.typ new file mode 100644 index 0000000..4515203 --- /dev/null +++ b/paged-out!/stop-using-trrs/main.typ @@ -0,0 +1,73 @@ +#import "template.typ": article + +#show ref: it => { + [(#it)] +} + +#show: article.with( + title: [Stop Using TRRS for Split-Keyboard Interconnects!], + authors: "Foo", +) + +TRRS (Tip Ring Ring Sleeve, or, as you may know it, "headphone jack with microphone support") cables have long been the go to connector between split keyboard halves. +They are cheap, compact, and thanks to their popularity, come in a variety of aesthetic styles. + +However, TRRS jacks were only designed for passive electrical components, and expose one large flaw when used actively. +When a TRRS cable is (dis)connected, the tip of the plug will slide past every single contact of the jack. +Likewise, the first contact of the jack will slide past every contact of the plug. + +To illustrate this, let us consider a TRRS setup where 5v is applied to the tip. +In this example, assume this plug is on the passive side of the board, receiving power from the active side plugged into USB. +When fully plugged in @5v_plugged_in, everything is connected properly. +However, when pulled out, 5v immediately makes contact with the TX line @5v_partial_plug. + +#grid(columns: 2, gutter: 20pt, +[#figure( + image("./trrs_fully_plugged_in_5v_tip.svg", fit: "contain"), + caption: "A 5v tip TRRS fully plugged in.", +) <5v_plugged_in>], +[#figure( + image("./trrs_partially_plugged_in_5v_tip.svg", fit: "contain"), + caption: "A 5v tip TRRS starting to be pulled out. Notice the short between 5v and Tx.", +) <5v_partial_plug>], +) + +When the 5v Aurdino Pro Micro dominated as a keyboard MCU, a brief short between 5v and Tx/Rx may have been acceptable. +However, due to the emergence of RP2040 powered drop in replacements for the Pro Micro, such as the Elite-pi or KB2040, +3.3v logic levels are now commonplace among keyboards. +Thus, shorting the 5v power line with a logic pin is a surefire way to burn out at least a GPIO, if not your whole MCU. + +Now, what if we put the 5v at the base, so that it is the first pin disconnected? + +#grid(columns: 2, gutter: 20pt, +[#figure( + image("./trrs_fully_plugged_in_5v_sleeve.svg", fit: "contain"), + caption: "A GND tip TRRS fully plugged in.", +) ], +[#figure( + image("./trrs_partially_plugged_in_5v_sleeve.svg", fit: "contain"), + caption: "A GND tip TRRS starting to be pulled out. Notice the short between 5v and Rx.", +) ], +) + +In this case, we are looking at the active side of the board, connected to USB, and supplying power to the passive side. +Now, when unplugged the 5v contact of the jack will immediately make contact with the Rx line, +pulling it up to 5v and damaging the pin on the passive side of the board. + +No matter what order we put the contacts in, +one end of the TRRS cable will be unsafe to unplug while powered. +No other electronics found in your home suffer permanent damage from simply being unplugged in the wrong order. +In a moment of carelessness or forgetfulness, damage to hardware could easily happen. + +So what are the alternatives? +USB-C, while almost as small as TRRS, are more expensive component wise and and +having the same connector for board-to-board and PC-to-board connections may lead to user error. +There are also a wide variety of JST and Molex connectors, some of which rival TRRS in size, +but premade cables are not readily available, +and many connectors have a tendency to work themselves loose over time. +My personal favorite are 4P4C connectors, also known as RJ9, RJ10, or RJ22. +While bulky on the PCB, the connection is sturdy, cables are availible, and one can make ones own cables with a cheap crimping tool. +There are of course other connectors, and any with at least 4 conductors will work for a split keyboard. +Unfortunately, there does not seem to be a perfect connector, but there are many alternatives better than TRRS. + +_This article is dedicated to the late pin D26 of Jonathan's Ferris Sweep. He is forever grateful that the Elite-pi has extra GPIOs._ diff --git a/paged-out!/stop-using-trrs/template.typ b/paged-out!/stop-using-trrs/template.typ new file mode 100644 index 0000000..5d3d87b --- /dev/null +++ b/paged-out!/stop-using-trrs/template.typ @@ -0,0 +1,36 @@ +#let article( + title: none, + authors: (), + date: datetime.today(), + margin: (x: 1mm, y: 1mm), + fontsize: 12pt, + doc, +) = { + //setup page size. Margin can be small because Paged Out! includes its own margins. + set page(width: 182mm, height: 253mm, margin: margin) + + //blue, web-style links. + show link: it => { + set text(blue) + underline(it) + } + + //Lets us fit a bit more text on the page without looking too cramped. + set text(size: fontsize) + set par(leading: 4pt, justify: true) + + //setup document metadata. (no clue if its useful to the Paged Out! pipeline, but just in case) + set document( + title: title, + author: authors, + date: date, + ) + + //setup top level headings. We leave styling the subheadings to the user. + show heading.where(level: 1): set text(size: 16pt) + + //render a title if one is provided. + if title != none { [= #title] } + + doc +} diff --git a/paged-out!/stop-using-trrs/trrs.svg b/paged-out!/stop-using-trrs/trrs.svg new file mode 100644 index 0000000..377ce63 --- /dev/null +++ b/paged-out!/stop-using-trrs/trrs.svg @@ -0,0 +1,213 @@ + + + + + + + + + + + + 5v + Rx + Tx + Gnd + + + + + + + + + + + + + + 5v + Rx + Tx + Gnd + + + + diff --git a/paged-out!/stop-using-trrs/trrs_fully_plugged_in_5v_sleeve.svg b/paged-out!/stop-using-trrs/trrs_fully_plugged_in_5v_sleeve.svg new file mode 100644 index 0000000..972d56e --- /dev/null +++ b/paged-out!/stop-using-trrs/trrs_fully_plugged_in_5v_sleeve.svg @@ -0,0 +1,160 @@ + + + + + + + + + 5v + Rx + Tx + Gnd + + + + + + + + + + + + + + 5v + Rx + Tx + Gnd + + + + diff --git a/paged-out!/stop-using-trrs/trrs_fully_plugged_in_5v_tip.svg b/paged-out!/stop-using-trrs/trrs_fully_plugged_in_5v_tip.svg new file mode 100644 index 0000000..0a40335 --- /dev/null +++ b/paged-out!/stop-using-trrs/trrs_fully_plugged_in_5v_tip.svg @@ -0,0 +1,160 @@ + + + + + + + + + Gnd + Rx + Tx + 5v + + + + + + + + + + + + + + Gnd + Rx + Tx + 5v + + + + diff --git a/paged-out!/stop-using-trrs/trrs_partially_plugged_in_5v_sleeve.svg b/paged-out!/stop-using-trrs/trrs_partially_plugged_in_5v_sleeve.svg new file mode 100644 index 0000000..75f136d --- /dev/null +++ b/paged-out!/stop-using-trrs/trrs_partially_plugged_in_5v_sleeve.svg @@ -0,0 +1,160 @@ + + + + + + + + + 5v + Rx + Tx + Gnd + + + + + + + + + + + + + + 5v + Rx + Tx + Gnd + + + + diff --git a/paged-out!/stop-using-trrs/trrs_partially_plugged_in_5v_tip.svg b/paged-out!/stop-using-trrs/trrs_partially_plugged_in_5v_tip.svg new file mode 100644 index 0000000..b6b9bb1 --- /dev/null +++ b/paged-out!/stop-using-trrs/trrs_partially_plugged_in_5v_tip.svg @@ -0,0 +1,160 @@ + + + + + + + + + Gnd + Rx + Tx + 5v + + + + + + + + + + + + + + Gnd + Rx + Tx + 5v + + + + diff --git a/paged-out!/typst-template/.gitignore b/paged-out!/typst-template/.gitignore new file mode 100644 index 0000000..a136337 --- /dev/null +++ b/paged-out!/typst-template/.gitignore @@ -0,0 +1 @@ +*.pdf diff --git a/paged-out!/typst-template/main.typ b/paged-out!/typst-template/main.typ new file mode 100644 index 0000000..42a4030 --- /dev/null +++ b/paged-out!/typst-template/main.typ @@ -0,0 +1,7 @@ +#import "template.typ": article + +#show: article.with( + title: [Paged Out! article], + authors: "Foo", +) +#lorem(850) diff --git a/paged-out!/typst-template/template.typ b/paged-out!/typst-template/template.typ new file mode 100644 index 0000000..5d3d87b --- /dev/null +++ b/paged-out!/typst-template/template.typ @@ -0,0 +1,36 @@ +#let article( + title: none, + authors: (), + date: datetime.today(), + margin: (x: 1mm, y: 1mm), + fontsize: 12pt, + doc, +) = { + //setup page size. Margin can be small because Paged Out! includes its own margins. + set page(width: 182mm, height: 253mm, margin: margin) + + //blue, web-style links. + show link: it => { + set text(blue) + underline(it) + } + + //Lets us fit a bit more text on the page without looking too cramped. + set text(size: fontsize) + set par(leading: 4pt, justify: true) + + //setup document metadata. (no clue if its useful to the Paged Out! pipeline, but just in case) + set document( + title: title, + author: authors, + date: date, + ) + + //setup top level headings. We leave styling the subheadings to the user. + show heading.where(level: 1): set text(size: 16pt) + + //render a title if one is provided. + if title != none { [= #title] } + + doc +}