Penguin Development - User contributions [en-gb]

Light glyph lamp

2024-01-04T22:21:06Z

Link: /* Testing the electronics */

The '''light glyph lamp''' is an open-source touch-activated LED lamp based on the light glyph seen in ''[[w:The Owl House|The Owl House]]''.

All source files can be found at [https://proj.penguindevelopment.org/light-glyph-lamp/].

[[File:Light-glyph-lamp_demo.gif|frame|Demonstration video]]

[[File:Light-glyph-lamp_pcb-assembled.jpg|thumb|128px|Printed circuit board, assembled]]

== 3D printable parts ==

The exterior parts of the lamp can be 3D printed. FDM is highly recommended for the structural parts, although the orb and diffuser may use resin instead. The STL files and OpenSCAD source code can be found at [https://proj.penguindevelopment.org/light-glyph-lamp/light-glyph-lamp_printable-parts-0.2.tar.xz].

=== Requirements ===

* FDM 3D printer
* ~150 g of filament

Diffuser and orb:
* ~50 g of translucent white filament
OR
* Resin printer
* ~30 ml of translucent white resin

Glyph:
* ~10 g of translucent dark filament
* Multi-extrusion capability (optional but recommended)
OR
* Translucent dark resin
* Syringe with large-bore (~0.5 mm) needle
* UV torch or laser pointer
* ~10 g of PVA filament

=== Main parts ===

The box and tube may be printed with any filament. In the demonstration video's build, [https://colorfabb.com/woodfill colorFabb woodFill] is used for the box, and [https://www.esun3d.com/epa-cf-product/ eSUN ePA-CF] is used for the tube. The tube can be printed lying on its side, but ''do not'' use supports.

The diffuser and orb should be printed in a translucent white filament or resin. In the demonstration video's build, [https://www.esun3d.com/eresin-pla-product/ clear eSUN eResin-PLA], dyed with SigWong white alcohol ink is used. Depending on the desired luminosity, the orb may get somewhat hot; in this case, PLA filament may be less suitable.

=== Faceplate and glyph ===

Printing the faceplate is somewhat more complex, as it requires two colours. Furthermore, the glyph should have a greater translucency than the other faceplate material, but a darker colour when not backlit. There are several ways to achieve this, two of which are highlighted here.

==== Pure FDM with multi-extrusion or filament swapping ====

In this approach, the STLs for the '''faceplate''' and the '''glyph''' are used. If using Cura as a slicer, set up a multi-extrusion printer, which [https://scholtzan.net/blog/cura-multicolor-single-extruder/ may be emulated using filament swaps]. Load the STLs, and assign each to its own extruder, then combine the models. In PrusaSlicer, first import the faceplate, then right-click and use "add part" to import the glyph. As in Cura, [https://forum.prusa3d.com/forum/postid/188236/ multi-extrusion may be emulated with filament swaps].

Few filaments exist which are dark but translucent. One possibility is the [https://www.matterhackers.com/store/l/translucent-grey-mh-build-series-petg-filament-175mm-1kg/sk/MX9SD5D4 translucent grey PETG by Matterhackers]. Although it is generally not recommended to mix filament types in multi-extrusion (as materials with different shrinkage rates tend to separate), the glyph STL contains a "hidden" brim, which allows it to stay mechanically locked to the faceplate even if two different materials are used.

==== Resin inlay ====

The resin inlay approach is used in the build shown in the demonstration video. Here, the glyph is not printed, but made manually using resin. This step requires a water-soluble filament such as '''PVA''', a dark-but-translucent 3D resin such as '''[https://www.esun3d.com/hard-tough-resin-product/ eSUN Hard-Tough black]''', a '''syringe''' with a large-diameter (~0.5 mm inner diameter) needle, and a '''UV torch or laser pointer'''.

The STLs to use are the '''faceplate''' and the '''raft'''. Place the raft on the build plate, and the faceplate on top of it, upside-down, ''without'' a gap. In the G-code, insert a filament change (M600) after 0.4 mm. Also insert a pause (M601) or filament change after 1.6 mm.

Start printing the raft using a water-soluble filament such as PVA. At the first M600, switch to the desired material for the faceplate. At the pause, use the syringe to deposit a ''thin'' layer of resin, ideally 0.1 mm or less, in the cutout where the glyph should be. Thoroughly cure the resin with the UV torch or laser pointer. '''N.B. make absolutely sure you obey basic resin safety guidelines, and in particular ''DO NOT breathe the fumes when curing''.''' Repeat this, in thin layers, until the entire cutout is filled, including the brim. Then resume the print, and when it finishes, again build up the remaining 0.6 mm of the glyph cutout with resin.

Finally, ''very carefully'' remove the print—raft and all—from the build plate, and place it in warm water until the raft is fully dissolved. N.B. being too aggressive when removing the print, or peeling off the raft before it has sufficiently dissolved, can cause the resin inlay to crack.

== Electronics ==

The electronics are designed with [http://www.geda-project.org/ gEDA]. The gschem and PCB files can be found at [https://proj.penguindevelopment.org/light-glyph-lamp/light-glyph-lamp_electronic-designs-0.2.tar.xz]. The PCB gerbers can be found at [https://proj.penguindevelopment.org/light-glyph-lamp/light-glyph-lamp_gerbers-0.2.zip]. The PCB is difficult to fabricate at home as it uses plated through-holes and vias with a small drill size; it is recommended to use a service like [https://jlcpcb.com/ JLCPCB] to manufacture the board (<€10 for 5 copies, including shipping). The gerber zip can be uploaded directly to JLCPCB. The components are all inexpensively available from AliExpress.

[[File:Light-glyph-lamp_pcb-front.jpg|thumb|128px|Front side of blank PCB]] [[File:Light-glyph-lamp_pcb-back.jpg|thumb|128px|Back side of blank PCB]]

=== Requirements ===

* Fine-tipped soldering iron (regulated station recommended)
* Needle-nose tweezers
* A steady hand—many components use a 0402 package
* AVR ISP programmer, e.g. [https://www.aliexpress.com/item/32869664871.html AVRISP MKII]
* Light glyph PCB
* 2× [https://www.aliexpress.com/item/1005006115949873.html TO220 heatsink] and [https://www.aliexpress.com/item/1005001602601725.html thermal pads] (optional but recommended)—fasten with M3x6 screws

Full BOM:
{| class="wikitable" style="margin:auto"
|+ Bill of materials
|-
! Component ID !! Package/footprint !! Value/part name !! AliExpress link
|-
| C1 || 0402 || 100 nF || [https://www.aliexpress.com/item/32965092877.html]
|-
| C2 || 0402 || 100 nF || [https://www.aliexpress.com/item/32965092877.html]
|-
| C3 || Pol SMD, 12.5 mm || 1000 µF || [https://www.aliexpress.com/item/1005002285145345.html]
|-
| C4 || 0603 || 1 µF || [https://www.aliexpress.com/item/32966526545.html]
|-
| C5 || 0402 || 100 nF || [https://www.aliexpress.com/item/32965092877.html]
|-
| C6 || Pol SMD, 6.3 mm || 100 µF || [https://www.aliexpress.com/item/1005002285145345.html]
|-
| C7 || 0603 || 1 µF || [https://www.aliexpress.com/item/32966526545.html]
|-
| C8 || 0402 || 100 nF || [https://www.aliexpress.com/item/32965092877.html]
|-
| C9 || Pol SMD, 6.3 mm || 100 µF || [https://www.aliexpress.com/item/1005002285145345.html]
|-
| C10 || 0402 || 10 nF || [https://www.aliexpress.com/item/32965092877.html]
|-
| C11 || 0402 || 10 nF || [https://www.aliexpress.com/item/32965092877.html]
|-
| CS || 0402 || 1.5 nF<ref group="lower-alpha">Value may vary; see "Sense capacitor" below</ref> || [https://www.aliexpress.com/item/32965092877.html]
|-
| CONN1 || Terminal, 5.08 mm pitch || Degson DG129-5.08-02P || [https://www.aliexpress.com/item/1005005975744435.html]
|-
| CONN2 || None; plated through hole || - || -
|-
| CONN3 || Terminal, 5.08 mm pitch || Degson DG129-5.08-02P || [https://www.aliexpress.com/item/1005005975744435.html]
|-
| D1-D48 || Through-hole LED, 3 mm || Warm white || [https://www.aliexpress.com/item/1005005881762668.html]
|-
| J1 || Header, 2×3, 2.54 mm pitch || Male ISP header || [https://www.aliexpress.com/item/1005006142829300.html]
|-
| J2 || Header, 1×3, 2.54 mm pitch || Male header || [https://www.aliexpress.com/item/1005003817088431.html]
|-
| J3 || Header, 1×3, 2.54 mm pitch || Male header || [https://www.aliexpress.com/item/1005003817088431.html]
|-
| Q1 || TO220W || IRLZ44N || [https://www.aliexpress.com/item/1005002474344551.html]
|-
| Q2 || TO220W || IRLZ44N || [https://www.aliexpress.com/item/1005002474344551.html]
|-
| R1 || 0603 || 100 kΩ || [https://www.aliexpress.com/item/1005002384017954.html]
|-
| R2 || 0603 || 100 kΩ || [https://www.aliexpress.com/item/1005002384017954.html]
|-
| R3 || 0603 || 10 kΩ || [https://www.aliexpress.com/item/1005002384017954.html]
|-
| R4 || 3296W trimpot || 10 kΩ || [https://www.aliexpress.com/item/1005006247969166.html]
|-
| R5 || 3296W trimpot || 10 kΩ || [https://www.aliexpress.com/item/1005006247969166.html]
|-
| R6-R21 || 0603 || 180 Ω<ref group="lower-alpha">Value may vary strongly depending on the 3 mm LEDs used. 180 Ω is appropriate for most white or blue LEDs; red/yellow/green LEDs typically need a significantly higher resistance.</ref> || [https://www.aliexpress.com/item/1005002384017954.html]
|-
| RS || 0603 || 10 kΩ || [https://www.aliexpress.com/item/1005002384017954.html]
|-
| U1 || SO14 || ATtiny44A || [https://www.aliexpress.com/item/4001135654697.html]
|-
| U2 || SOT23-6 || AT42QT1010 || [https://www.aliexpress.com/item/1005006079721484.html]
|-
| U3 || SOT223 || AMS1117-5.0 || [https://www.aliexpress.com/item/1005001424098090.html]
|-
| U4 || SOT223 || AMS1117-5.0 || [https://www.aliexpress.com/item/1005001424098090.html]
|}
<references group="lower-alpha" />

=== Electronics assembly ===

Soldering the components is reasonably straight-forward. First solder the SMD resistors (R6-R21) on the front side. Then flip to the back side and solder the SMD components by increasing height, starting with the 0402 capacitors and ending with the 1000 µF capacitor. Attach the heatsinks to the TO220W MOSFETs and place them on the backside (the heatsink aligns with the markings on the board). Then solder the trim potentiometers and the connectors. CONN1 and CONN3. Note that these should both face towards the centre line of the board. Leave CONN2 open for the time being; we will make and connect a sense pad on the glyph later.

Finally, flip to the front side and install the 3 mm LEDs, inserting them up to the "wings" on the pins. Note that '''the square hole is the ''cathode''''', i.e. the '''short''' pin of the LEDs. Trim the legs off the LEDs.

=== Flashing the firmware ===

The firmware and source code can be found at [https://proj.penguindevelopment.org/light-glyph-lamp/light-glyph-lamp_firmware-0.2.tar.xz]. To flash it, connect the ISP programmer to the ISP header J1, taking note of the correct orientation. '''DO NOT''' connect 12V power; the programmer should power the circuit. N.B. the "Orb BRT" text on the PCB should be ignored at this stage.

Flashing is easily done using AVRDUDE, e.g. <syntaxhighlight>avrdude -p t44 -c avrispmkII -U flash:w:flash.hex</syntaxhighlight>

=== Sense capacitor ===

One point of trial and error exists in the sense capacitor, CS. Typically, a value between 1 and 10 nF should be used, with higher values increasing touch sensitivity as well as noise sensitivity. It is highly recommended to have several values within this range available and experiment until you find the best option. Choosing a value that is too small will make the lamp unresponsive to touch, or only sensitive to touch with a full hand. On the other hand, choosing a value that is too large may cause the lamp to oscillate between off and on states.

== Assembly ==

=== Requirements ===

* 12V adapter with 5.5 mm × 2.5 mm barrel connector, e.g. [https://www.aliexpress.com/item/1005003282695860.html]
* 12V LED strip, ~30 cm, e.g. [https://www.aliexpress.com/item/32809840774.html]
* [https://www.aliexpress.com/item/1005002601060281.html 5.5 mm × 2.5 barrel connector, female]
* ~50 cm each of red and black hookup wire
* ~4 mm diameter and ~10 mm diameter heat shrink tubing (optional but recommended)
* 4× [https://www.aliexpress.com/item/1005006355377113.html M3x12 screws]
* [https://www.aliexpress.com/item/1005004654217011.html 70 mm copper tape]
* [https://www.aliexpress.com/item/4001160286339.html 0.3 mm enamelled copper wire]
* [https://www.aliexpress.com/item/1005005016478093.html Silver conductive glue]
* Small-tipped hobby knife, e.g. [https://www.xacto.com/knives-blades.html X-Acto]
* Multimeter
* Soldering iron
* 4× [https://www.aliexpress.com/item/1005004535859664.html M3 brass inserts, 5 mm outer diameter]
* Hot glue gun
* 2× [https://www.aliexpress.com/item/10000002338839.html 2.54 mm header jumper]
* Flat-head jeweller's screwdriver

=== Making the sense pad ===

On the back side of the face plate, cover everything inside the glyph circle with copper tape, then cut out and remove the glyph lines from the tape using the hobby knife. Hold the faceplate in front of a light and look at it from the front to verify no tape obscures any part of the glyph lines.

Strip the enamel from ~8 cm of the copper wire, and cut the stripped wire into ~1 cm pieces. With the faceplate face-down and the "arrow" of the glyph pointing away from you, start at the copper tape "island" at the lower right, and place the lengths of copper wire across the glyph lines until all islands are connected. There should be a single current path from every island to the one on the lower right; make sure there are no loops. Fix the wires in place with the conductive glue.

Now take around 10 cm of copper wire, and strip the first 2 or 3 centimetres. Bend the stripped end into a zig-zag or spiral, and place it on the lower right island, with the unstripped tail pointing toward the lower-right standoff. Again fix the stripped wire in place with the conductive glue. The glue will not be conductive until it has fully set; this takes several hours, and you should leave the faceplate in a safe location for the full duration. While you wait for the glue to set (it is recommended to leave it overnight), you can assemble the orb and power connector.

=== Orb assembly ===

Begin by preparing a ~30 cm length of LED strip. Completely remove the adhesive tape (not just the protective film that covers it), and attach ~35 cm leads using the red and black hookup wires (red on +, black on -). Secure the solder joints with heat shrink tubing (or insulation tape), using just enough to cover the joints. Feed the LED strip into the orb, using a thin, blunt pin or pointy tweezers to manipulate it on the inside, if necessary. Continue until only the leads stick out.

Feed the other end of the leads into the short end of the tube, until they come out of the other end. Gently pull from the long side until you can insert the short side into the orb until you hit the square fins. At this point, you may opt to leave the the tube out of the box to make for easier testing later; in this case, strip around 6 mm of insulation from the ends of the leads. However, if you wish to proceed, insert the remainder of the leads down the channel at the back of the box, and use needle-nose tweezers or pliers to pull them further into the box. Again, gently pull, now inserting the long side of the tube into the channel until you hit the square fins on that side.

If necessary, trim down the leads so about 10 cm is inside the box. Strip around 6 mm of insulation from the ends.

=== Power connector assembly ===

Take the female barrel connector and attach ~10 cm black and red leads. The red one (+) should go on the short pin and the black on the long pin (-), although it is a good idea to first connect the 12V adapter and verify the polarity. Optionally insulate the connection with some heat shrink tubing.

At this point, you may wish to leave the connector out of the box to make for easier testing, and install it later. If so, strip around 6 mm of insulation from the ends of the leads. Otherwise, insert the leads from the outside of the box into the small truncated circular hole in the back. Push the barrel connector into the hole, noting the flat sides. From the inside, feed the leads through the nut included with the barrel connector. Fasten the nut onto the connector with your fingers and tighten it with needle-nose pliers. Finally, strip ~6 mm of insulation from the end of the leads.

=== Faceplate and electronic assembly ===

Once the conductive glue on the faceplate wires has set, verify electrical continuity across the copper islands with a multimeter, or (les ideally) with a low-power LED indicator. To do so, ''carefully'' strip a few millimetres of enamel off the wire "tail" pointing away from the lower-right copper island (lower-left if seen from the front). Probe the resistance/continuity between this stripped end and each of the copper islands. No connection should read more than a few tens of ohms, tops.

Now slide the diffuser over the standoffs. The flat side of the diffuser should face towards the glyph. Insert the brass inserts into the standoff holes and push them in using a soldering iron until they are flush with the surface. Leave them to cool off for a minute or so.

Take the assembled PCB and fix it onto the faceplate with the 4 M3x12 screws. Do not tighten the screws. Ensure that the 3 mm LEDs face towards the diffuser and are aligned with the glyph. The copper wire tail should be close to CONN2 on the PCB. With some needle-nose tweezers, gently feed this copper wire through the CONN2 hole from the LED side. Pull it through the hole until there's around 5 mm of slack against the side of the diffuser. Do not pull hard; the conductive glue is very weak and you may tear it otherwise. Now solder the copper wire onto the CONN2 hole on the component side. You will need to melt through the insulating enamel before you can make an electrical connection, so be patient. Verify the connection between CONN2 and the copper islands on the faceplate, then trim the excess copper wire. (This is important, as it will interfere with the capacitive touch sensor.)

=== Testing the electronics ===

Insert the leads for the power jack into the terminal labelled "PWR" and tighten the screws. Note that the ground (black wire) should be closest to the board edge. Then attach the orb leads to the terminal labelled "Orb", noting that the connections are reversed: here, +12 V (red wire) should be closest to the board edge.

Place one of the jumpers across the top pins of J2, labelled "Glyph BRT" (BRT stands for BRightness Test), and the other across the GND and MOSI pins of J1, labelled "Orb BRT". Now connect the 12V adapter to the barrel jack and insert it in the wall socket. If everything is OK, the glyph should light up. You can now use the potentiometer R4, labelled "glyph", to adjust the brightness. Once you are satisfied, remove the Glyph BRT jumper, ''carefully''' so as to not create a short-circuit (you may disconnect power first to eliminate the risk). The glyph should turn off and the orb should turn on. Adjust the brightness until you are satisfied, then remove the Orb BRT jumper.

Now, all LEDs should be off, and the lamp will enter idle mode. At this point, touching the front of the glyph should cause it to light up briefly, after which the orb turns on, as in the demonstration video. If it does not, it usually means the value of CS is too low; see "Sense capacitor" in the previous section. However, if increasing CS does not make the lamp responsive to touch, you can try touching the wire stub at CONN2 directly (make sure your hands are dry). If this does turn the lamp on, it means the copper tape on the glyph is not properly connected to CONN2. If it still does not turn on when touching CONN2 while having a large (≥ 10 nF) CS, you have most likely damaged U2 (the touch sensor, not the band) or another component when soldering.

=== Finishing up ===

Once the electronics work as desired, disconnect power and use some hot glue around the corners of the PCB to secure it gently to the faceplate and diffuser. Use only a small drop; you do not want to cover any electronic components or get glue in the screw threads. It should be easy to peel off at a later stage, if desired.

Now remove the M3x12 screws holding the board in place. At this stage, make sure the BRT jumpers are removed! Then turn the assembly over and place it in the box. Insert the M3x12 screws from the bottom side of the box and gently tighten them. Take care not to over-tighten, particularly if you used woodFill, as this is a weak filament and can easily be damaged by twisting.

Finally, reconnect power. You should see the glyph and orb flash briefly, in sequence, and then turn off. Ensure the lamp properly responds to touch. Congratulations, you're done, hoot hoot!

== Troubleshooting and notes ==

Occasionally, the lamp may start oscillating between states. In the current version, this can sometimes be stopped by pushing down on the glyph with a full hand or by grabbing the box from the sides, but the only sure-fire way to stop it is to temporarily disconnect power. This will hopefully be eliminated in a future revision by letting the microcontroller reset the touch sensor. In the mean time, use the smallest possible value for CS that you can get away with to minimise the failure rate.

For advanced users, the current revision of the board allows you to use an external trigger signal, e.g. from a [https://www.aliexpress.com/item/1005005762960287.html TTP223 board]. To do so, remove the AT42QT1010 (U2) and attach the external board to the TRIG pin CONN4. In the default configuration, the external trigger should be an active-high push-pull output. To use an active-low signal, define <code>TRIG_ACTIVE_LOW</code> in the firmware. To use an open-drain trigger signal, remove R3 and define <code>TRIG_OPEN_DRAIN</code> in the firmware.

Main Page

2024-01-04T18:18:34Z

Link: /* Hardware */

Welcome to '''Penguin Development'''! We make [[w:free and open-source software|free and open-source software]] and [[w:Open-source hardware|hardware]].

See below for current releases. All software and hardware is licensed under the [https://gnu.org/licenses/gpl.html GPL] (version 3 or higher) unless otherwise stated.

=Software=
* [[AUTOMOME]] — the OTTish AUTOMEME clone
* [[Ising]] — Monte Carlo Ising model simulator
* [[stackermann]] — a stack-based [[w:Ackermann function|Ackermann function]] calculator
* [[catan-gen]] — convergent map creation app for [https://www.catan.com/ Catan]

=Hardware=
* [[Light glyph lamp]] — Capacitive touch lamp based on the light glyph from ''The Owl House''
* [[timelapse]] — time-lapse trigger for digital cameras

=Code snippets and how-tos=
* [[Animated 3D plotting with Blender]]
* [[Matrix Synapse and mautrix-whatsapp in a VPN]]

Light glyph lamp

2024-01-04T18:17:52Z

Link: Created page with "The '''light glyph lamp''' is an open-source touch-activated LED lamp based on the light glyph seen in ''The Owl House''. All source files can be found at [https://proj.penguindevelopment.org/light-glyph-lamp/]. Demonstration video Printed circuit board, assembled == 3D printable parts == The exterior parts of the lamp can be 3D printed. FDM is highl..."

The '''light glyph lamp''' is an open-source touch-activated LED lamp based on the light glyph seen in ''[[w:The Owl House|The Owl House]]''.

All source files can be found at [https://proj.penguindevelopment.org/light-glyph-lamp/].

[[File:Light-glyph-lamp_demo.gif|frame|Demonstration video]]

[[File:Light-glyph-lamp_pcb-assembled.jpg|thumb|128px|Printed circuit board, assembled]]

== 3D printable parts ==

The exterior parts of the lamp can be 3D printed. FDM is highly recommended for the structural parts, although the orb and diffuser may use resin instead. The STL files and OpenSCAD source code can be found at [https://proj.penguindevelopment.org/light-glyph-lamp/light-glyph-lamp_printable-parts-0.2.tar.xz].

=== Requirements ===

* FDM 3D printer
* ~150 g of filament

Diffuser and orb:
* ~50 g of translucent white filament
OR
* Resin printer
* ~30 ml of translucent white resin

Glyph:
* ~10 g of translucent dark filament
* Multi-extrusion capability (optional but recommended)
OR
* Translucent dark resin
* Syringe with large-bore (~0.5 mm) needle
* UV torch or laser pointer
* ~10 g of PVA filament

=== Main parts ===

The box and tube may be printed with any filament. In the demonstration video's build, [https://colorfabb.com/woodfill colorFabb woodFill] is used for the box, and [https://www.esun3d.com/epa-cf-product/ eSUN ePA-CF] is used for the tube. The tube can be printed lying on its side, but ''do not'' use supports.

The diffuser and orb should be printed in a translucent white filament or resin. In the demonstration video's build, [https://www.esun3d.com/eresin-pla-product/ clear eSUN eResin-PLA], dyed with SigWong white alcohol ink is used. Depending on the desired luminosity, the orb may get somewhat hot; in this case, PLA filament may be less suitable.

=== Faceplate and glyph ===

Printing the faceplate is somewhat more complex, as it requires two colours. Furthermore, the glyph should have a greater translucency than the other faceplate material, but a darker colour when not backlit. There are several ways to achieve this, two of which are highlighted here.

==== Pure FDM with multi-extrusion or filament swapping ====

In this approach, the STLs for the '''faceplate''' and the '''glyph''' are used. If using Cura as a slicer, set up a multi-extrusion printer, which [https://scholtzan.net/blog/cura-multicolor-single-extruder/ may be emulated using filament swaps]. Load the STLs, and assign each to its own extruder, then combine the models. In PrusaSlicer, first import the faceplate, then right-click and use "add part" to import the glyph. As in Cura, [https://forum.prusa3d.com/forum/postid/188236/ multi-extrusion may be emulated with filament swaps].

Few filaments exist which are dark but translucent. One possibility is the [https://www.matterhackers.com/store/l/translucent-grey-mh-build-series-petg-filament-175mm-1kg/sk/MX9SD5D4 translucent grey PETG by Matterhackers]. Although it is generally not recommended to mix filament types in multi-extrusion (as materials with different shrinkage rates tend to separate), the glyph STL contains a "hidden" brim, which allows it to stay mechanically locked to the faceplate even if two different materials are used.

==== Resin inlay ====

The resin inlay approach is used in the build shown in the demonstration video. Here, the glyph is not printed, but made manually using resin. This step requires a water-soluble filament such as '''PVA''', a dark-but-translucent 3D resin such as '''[https://www.esun3d.com/hard-tough-resin-product/ eSUN Hard-Tough black]''', a '''syringe''' with a large-diameter (~0.5 mm inner diameter) needle, and a '''UV torch or laser pointer'''.

The STLs to use are the '''faceplate''' and the '''raft'''. Place the raft on the build plate, and the faceplate on top of it, upside-down, ''without'' a gap. In the G-code, insert a filament change (M600) after 0.4 mm. Also insert a pause (M601) or filament change after 1.6 mm.

Start printing the raft using a water-soluble filament such as PVA. At the first M600, switch to the desired material for the faceplate. At the pause, use the syringe to deposit a ''thin'' layer of resin, ideally 0.1 mm or less, in the cutout where the glyph should be. Thoroughly cure the resin with the UV torch or laser pointer. '''N.B. make absolutely sure you obey basic resin safety guidelines, and in particular ''DO NOT breathe the fumes when curing''.''' Repeat this, in thin layers, until the entire cutout is filled, including the brim. Then resume the print, and when it finishes, again build up the remaining 0.6 mm of the glyph cutout with resin.

Finally, ''very carefully'' remove the print—raft and all—from the build plate, and place it in warm water until the raft is fully dissolved. N.B. being too aggressive when removing the print, or peeling off the raft before it has sufficiently dissolved, can cause the resin inlay to crack.

== Electronics ==

The electronics are designed with [http://www.geda-project.org/ gEDA]. The gschem and PCB files can be found at [https://proj.penguindevelopment.org/light-glyph-lamp/light-glyph-lamp_electronic-designs-0.2.tar.xz]. The PCB gerbers can be found at [https://proj.penguindevelopment.org/light-glyph-lamp/light-glyph-lamp_gerbers-0.2.zip]. The PCB is difficult to fabricate at home as it uses plated through-holes and vias with a small drill size; it is recommended to use a service like [https://jlcpcb.com/ JLCPCB] to manufacture the board (<€10 for 5 copies, including shipping). The gerber zip can be uploaded directly to JLCPCB. The components are all inexpensively available from AliExpress.

[[File:Light-glyph-lamp_pcb-front.jpg|thumb|128px|Front side of blank PCB]] [[File:Light-glyph-lamp_pcb-back.jpg|thumb|128px|Back side of blank PCB]]

=== Requirements ===

* Fine-tipped soldering iron (regulated station recommended)
* Needle-nose tweezers
* A steady hand—many components use a 0402 package
* AVR ISP programmer, e.g. [https://www.aliexpress.com/item/32869664871.html AVRISP MKII]
* Light glyph PCB
* 2× [https://www.aliexpress.com/item/1005006115949873.html TO220 heatsink] and [https://www.aliexpress.com/item/1005001602601725.html thermal pads] (optional but recommended)—fasten with M3x6 screws

Full BOM:
{| class="wikitable" style="margin:auto"
|+ Bill of materials
|-
! Component ID !! Package/footprint !! Value/part name !! AliExpress link
|-
| C1 || 0402 || 100 nF || [https://www.aliexpress.com/item/32965092877.html]
|-
| C2 || 0402 || 100 nF || [https://www.aliexpress.com/item/32965092877.html]
|-
| C3 || Pol SMD, 12.5 mm || 1000 µF || [https://www.aliexpress.com/item/1005002285145345.html]
|-
| C4 || 0603 || 1 µF || [https://www.aliexpress.com/item/32966526545.html]
|-
| C5 || 0402 || 100 nF || [https://www.aliexpress.com/item/32965092877.html]
|-
| C6 || Pol SMD, 6.3 mm || 100 µF || [https://www.aliexpress.com/item/1005002285145345.html]
|-
| C7 || 0603 || 1 µF || [https://www.aliexpress.com/item/32966526545.html]
|-
| C8 || 0402 || 100 nF || [https://www.aliexpress.com/item/32965092877.html]
|-
| C9 || Pol SMD, 6.3 mm || 100 µF || [https://www.aliexpress.com/item/1005002285145345.html]
|-
| C10 || 0402 || 10 nF || [https://www.aliexpress.com/item/32965092877.html]
|-
| C11 || 0402 || 10 nF || [https://www.aliexpress.com/item/32965092877.html]
|-
| CS || 0402 || 1.5 nF<ref group="lower-alpha">Value may vary; see "Sense capacitor" below</ref> || [https://www.aliexpress.com/item/32965092877.html]
|-
| CONN1 || Terminal, 5.08 mm pitch || Degson DG129-5.08-02P || [https://www.aliexpress.com/item/1005005975744435.html]
|-
| CONN2 || None; plated through hole || - || -
|-
| CONN3 || Terminal, 5.08 mm pitch || Degson DG129-5.08-02P || [https://www.aliexpress.com/item/1005005975744435.html]
|-
| D1-D48 || Through-hole LED, 3 mm || Warm white || [https://www.aliexpress.com/item/1005005881762668.html]
|-
| J1 || Header, 2×3, 2.54 mm pitch || Male ISP header || [https://www.aliexpress.com/item/1005006142829300.html]
|-
| J2 || Header, 1×3, 2.54 mm pitch || Male header || [https://www.aliexpress.com/item/1005003817088431.html]
|-
| J3 || Header, 1×3, 2.54 mm pitch || Male header || [https://www.aliexpress.com/item/1005003817088431.html]
|-
| Q1 || TO220W || IRLZ44N || [https://www.aliexpress.com/item/1005002474344551.html]
|-
| Q2 || TO220W || IRLZ44N || [https://www.aliexpress.com/item/1005002474344551.html]
|-
| R1 || 0603 || 100 kΩ || [https://www.aliexpress.com/item/1005002384017954.html]
|-
| R2 || 0603 || 100 kΩ || [https://www.aliexpress.com/item/1005002384017954.html]
|-
| R3 || 0603 || 10 kΩ || [https://www.aliexpress.com/item/1005002384017954.html]
|-
| R4 || 3296W trimpot || 10 kΩ || [https://www.aliexpress.com/item/1005006247969166.html]
|-
| R5 || 3296W trimpot || 10 kΩ || [https://www.aliexpress.com/item/1005006247969166.html]
|-
| R6-R21 || 0603 || 180 Ω<ref group="lower-alpha">Value may vary strongly depending on the 3 mm LEDs used. 180 Ω is appropriate for most white or blue LEDs; red/yellow/green LEDs typically need a significantly higher resistance.</ref> || [https://www.aliexpress.com/item/1005002384017954.html]
|-
| RS || 0603 || 10 kΩ || [https://www.aliexpress.com/item/1005002384017954.html]
|-
| U1 || SO14 || ATtiny44A || [https://www.aliexpress.com/item/4001135654697.html]
|-
| U2 || SOT23-6 || AT42QT1010 || [https://www.aliexpress.com/item/1005006079721484.html]
|-
| U3 || SOT223 || AMS1117-5.0 || [https://www.aliexpress.com/item/1005001424098090.html]
|-
| U4 || SOT223 || AMS1117-5.0 || [https://www.aliexpress.com/item/1005001424098090.html]
|}
<references group="lower-alpha" />

=== Electronics assembly ===

Soldering the components is reasonably straight-forward. First solder the SMD resistors (R6-R21) on the front side. Then flip to the back side and solder the SMD components by increasing height, starting with the 0402 capacitors and ending with the 1000 µF capacitor. Attach the heatsinks to the TO220W MOSFETs and place them on the backside (the heatsink aligns with the markings on the board). Then solder the trim potentiometers and the connectors. CONN1 and CONN3. Note that these should both face towards the centre line of the board. Leave CONN2 open for the time being; we will make and connect a sense pad on the glyph later.

Finally, flip to the front side and install the 3 mm LEDs, inserting them up to the "wings" on the pins. Note that '''the square hole is the ''cathode''''', i.e. the '''short''' pin of the LEDs. Trim the legs off the LEDs.

=== Flashing the firmware ===

The firmware and source code can be found at [https://proj.penguindevelopment.org/light-glyph-lamp/light-glyph-lamp_firmware-0.2.tar.xz]. To flash it, connect the ISP programmer to the ISP header J1, taking note of the correct orientation. '''DO NOT''' connect 12V power; the programmer should power the circuit. N.B. the "Orb BRT" text on the PCB should be ignored at this stage.

Flashing is easily done using AVRDUDE, e.g. <syntaxhighlight>avrdude -p t44 -c avrispmkII -U flash:w:flash.hex</syntaxhighlight>

=== Sense capacitor ===

One point of trial and error exists in the sense capacitor, CS. Typically, a value between 1 and 10 nF should be used, with higher values increasing touch sensitivity as well as noise sensitivity. It is highly recommended to have several values within this range available and experiment until you find the best option. Choosing a value that is too small will make the lamp unresponsive to touch, or only sensitive to touch with a full hand. On the other hand, choosing a value that is too large may cause the lamp to oscillate between off and on states.

== Assembly ==

=== Requirements ===

* 12V adapter with 5.5 mm × 2.5 mm barrel connector, e.g. [https://www.aliexpress.com/item/1005003282695860.html]
* 12V LED strip, ~30 cm, e.g. [https://www.aliexpress.com/item/32809840774.html]
* [https://www.aliexpress.com/item/1005002601060281.html 5.5 mm × 2.5 barrel connector, female]
* ~50 cm each of red and black hookup wire
* ~4 mm diameter and ~10 mm diameter heat shrink tubing (optional but recommended)
* 4× [https://www.aliexpress.com/item/1005006355377113.html M3x12 screws]
* [https://www.aliexpress.com/item/1005004654217011.html 70 mm copper tape]
* [https://www.aliexpress.com/item/4001160286339.html 0.3 mm enamelled copper wire]
* [https://www.aliexpress.com/item/1005005016478093.html Silver conductive glue]
* Small-tipped hobby knife, e.g. [https://www.xacto.com/knives-blades.html X-Acto]
* Multimeter
* Soldering iron
* 4× [https://www.aliexpress.com/item/1005004535859664.html M3 brass inserts, 5 mm outer diameter]
* Hot glue gun
* 2× [https://www.aliexpress.com/item/10000002338839.html 2.54 mm header jumper]
* Flat-head jeweller's screwdriver

=== Making the sense pad ===

On the back side of the face plate, cover everything inside the glyph circle with copper tape, then cut out and remove the glyph lines from the tape using the hobby knife. Hold the faceplate in front of a light and look at it from the front to verify no tape obscures any part of the glyph lines.

Strip the enamel from ~8 cm of the copper wire, and cut the stripped wire into ~1 cm pieces. With the faceplate face-down and the "arrow" of the glyph pointing away from you, start at the copper tape "island" at the lower right, and place the lengths of copper wire across the glyph lines until all islands are connected. There should be a single current path from every island to the one on the lower right; make sure there are no loops. Fix the wires in place with the conductive glue.

Now take around 10 cm of copper wire, and strip the first 2 or 3 centimetres. Bend the stripped end into a zig-zag or spiral, and place it on the lower right island, with the unstripped tail pointing toward the lower-right standoff. Again fix the stripped wire in place with the conductive glue. The glue will not be conductive until it has fully set; this takes several hours, and you should leave the faceplate in a safe location for the full duration. While you wait for the glue to set (it is recommended to leave it overnight), you can assemble the orb and power connector.

=== Orb assembly ===

Begin by preparing a ~30 cm length of LED strip. Completely remove the adhesive tape (not just the protective film that covers it), and attach ~35 cm leads using the red and black hookup wires (red on +, black on -). Secure the solder joints with heat shrink tubing (or insulation tape), using just enough to cover the joints. Feed the LED strip into the orb, using a thin, blunt pin or pointy tweezers to manipulate it on the inside, if necessary. Continue until only the leads stick out.

Feed the other end of the leads into the short end of the tube, until they come out of the other end. Gently pull from the long side until you can insert the short side into the orb until you hit the square fins. At this point, you may opt to leave the the tube out of the box to make for easier testing later; in this case, strip around 6 mm of insulation from the ends of the leads. However, if you wish to proceed, insert the remainder of the leads down the channel at the back of the box, and use needle-nose tweezers or pliers to pull them further into the box. Again, gently pull, now inserting the long side of the tube into the channel until you hit the square fins on that side.

If necessary, trim down the leads so about 10 cm is inside the box. Strip around 6 mm of insulation from the ends.

=== Power connector assembly ===

Take the female barrel connector and attach ~10 cm black and red leads. The red one (+) should go on the short pin and the black on the long pin (-), although it is a good idea to first connect the 12V adapter and verify the polarity. Optionally insulate the connection with some heat shrink tubing.

At this point, you may wish to leave the connector out of the box to make for easier testing, and install it later. If so, strip around 6 mm of insulation from the ends of the leads. Otherwise, insert the leads from the outside of the box into the small truncated circular hole in the back. Push the barrel connector into the hole, noting the flat sides. From the inside, feed the leads through the nut included with the barrel connector. Fasten the nut onto the connector with your fingers and tighten it with needle-nose pliers. Finally, strip ~6 mm of insulation from the end of the leads.

=== Faceplate and electronic assembly ===

Once the conductive glue on the faceplate wires has set, verify electrical continuity across the copper islands with a multimeter, or (les ideally) with a low-power LED indicator. To do so, ''carefully'' strip a few millimetres of enamel off the wire "tail" pointing away from the lower-right copper island (lower-left if seen from the front). Probe the resistance/continuity between this stripped end and each of the copper islands. No connection should read more than a few tens of ohms, tops.

Now slide the diffuser over the standoffs. The flat side of the diffuser should face towards the glyph. Insert the brass inserts into the standoff holes and push them in using a soldering iron until they are flush with the surface. Leave them to cool off for a minute or so.

Take the assembled PCB and fix it onto the faceplate with the 4 M3x12 screws. Do not tighten the screws. Ensure that the 3 mm LEDs face towards the diffuser and are aligned with the glyph. The copper wire tail should be close to CONN2 on the PCB. With some needle-nose tweezers, gently feed this copper wire through the CONN2 hole from the LED side. Pull it through the hole until there's around 5 mm of slack against the side of the diffuser. Do not pull hard; the conductive glue is very weak and you may tear it otherwise. Now solder the copper wire onto the CONN2 hole on the component side. You will need to melt through the insulating enamel before you can make an electrical connection, so be patient. Verify the connection between CONN2 and the copper islands on the faceplate, then trim the excess copper wire. (This is important, as it will interfere with the capacitive touch sensor.)

=== Testing the electronics ===

Insert the leads for the power jack into the terminal labelled "PWR" and tighten the screws. Note that the ground (black wire) should be closest to the board edge. Then attach the orb leads to the terminal labelled "Orb", noting that the connections are reversed: here, +12 V (red wire) should be closest to the board edge.

Place one of the jumpers across the top pins of J2, labelled "Glyph BRT" (BRT stands for BRightness Test), and the other across the GND and MOSI pins of J1, labelled "Orb BRT". Now connect the 12V adapter to the barrel jack and insert it in the wall socket. If everything is OK, the glyph should light up. You can now use the potentiometer R4, labelled "glyph", to adjust the brightness. Once you are satisfied, remove the Glyph BRT jumper, ''carefully''' so as to not create a short-circuit (you may disconnect power first to eliminate the risk). The glyph should turn off and the orb should turn on. Adjust the brightness until you are satisfied, then remove the Orb BRT jumper.

Now, all LEDs should be off, and the lamp will enter idle mode. At this point, touching the front of the glyph should cause it to light up briefly, after which the orb turns on, as in the demonstration video. If it does not, it usually means the value of CS is too low; see "Sense capacitor" in the previous section. However, increasing CS does not make the lamp responsive to touch, you can try touching the wire stub at CONN2 directly (make sure your hands are dry). If this does turn the lamp on, it means the copper tape on the glyph is not properly connected to CONN2. If it still does not turn on when touching CONN2 while having a large (≥ 10 nF) CS, you have most likely damaged U2 (the touch sensor, not the band) or another component when soldering.

=== Finishing up ===

Once the electronics work as desired, disconnect power and use some hot glue around the corners of the PCB to secure it gently to the faceplate and diffuser. Use only a small drop; you do not want to cover any electronic components or get glue in the screw threads. It should be easy to peel off at a later stage, if desired.

Now remove the M3x12 screws holding the board in place. At this stage, make sure the BRT jumpers are removed! Then turn the assembly over and place it in the box. Insert the M3x12 screws from the bottom side of the box and gently tighten them. Take care not to over-tighten, particularly if you used woodFill, as this is a weak filament and can easily be damaged by twisting.

Finally, reconnect power. You should see the glyph and orb flash briefly, in sequence, and then turn off. Ensure the lamp properly responds to touch. Congratulations, you're done, hoot hoot!

== Troubleshooting and notes ==

Occasionally, the lamp may start oscillating between states. In the current version, this can sometimes be stopped by pushing down on the glyph with a full hand or by grabbing the box from the sides, but the only sure-fire way to stop it is to temporarily disconnect power. This will hopefully be eliminated in a future revision by letting the microcontroller reset the touch sensor. In the mean time, use the smallest possible value for CS that you can get away with to minimise the failure rate.

For advanced users, the current revision of the board allows you to use an external trigger signal, e.g. from a [https://www.aliexpress.com/item/1005005762960287.html TTP223 board]. To do so, remove the AT42QT1010 (U2) and attach the external board to the TRIG pin CONN4. In the default configuration, the external trigger should be an active-high push-pull output. To use an active-low signal, define <code>TRIG_ACTIVE_LOW</code> in the firmware. To use an open-drain trigger signal, remove R3 and define <code>TRIG_OPEN_DRAIN</code> in the firmware.

File:Light-glyph-lamp demo.gif

2024-01-04T17:55:29Z

Link: Light glyph lamp demonstration.

== Summary ==
Light glyph lamp demonstration.

File:Light-glyph-lamp pcb-back.jpg

2024-01-04T16:36:54Z

Link: Light glyph lamp PCB, back side, as fabricated by JLCPCB.

== Summary ==
Light glyph lamp PCB, back side, as fabricated by JLCPCB.

File:Light-glyph-lamp pcb-front.jpg

2024-01-04T16:33:47Z

Link: Light glyph lamp PCB, front side, as fabricated by JLCPCB.

== Summary ==
Light glyph lamp PCB, front side, as fabricated by JLCPCB.

File:Light-glyph-lamp pcb-assembled.jpg

2024-01-04T16:30:37Z

Link: Light glyph lamp PCB with components soldered, and attached to the faceplate.

== Summary ==
Light glyph lamp PCB with components soldered, and attached to the faceplate.

MediaWiki:Cite link label group-lower-alpha

2024-01-04T09:29:21Z

Link: Created page with "a b c d e f g h i j k l m n o p q r s t u v w x y z aa ab ac ad ae af ag ah ai aj ak al am an ao ap aq ar as at au av aw ax ay az ba bb bc bd be bf bg bh bi bj bk bl bm bn bo bp bq br bs bt bu bv bw bx by bz ca cb cc cd ce cf cg ch ci cj ck cl cm cn co cp cq cr cs ct cu cv cw cx cy cz da db dc dd de df dg dh di dj dk dl dm dn do dp dq dr ds dt du dv dw dx dy dz ea eb ec ed ee ef eg eh ei ej ek el em en eo ep eq er es et eu ev ew ex ey ez fa fb fc fd fe ff fg fh fi fj fk..."

a b c d e f g h i j k l m n o p q r s t u v w x y z aa ab ac ad ae af ag ah ai aj ak al am an ao ap aq ar as at au av aw ax ay az ba bb bc bd be bf bg bh bi bj bk bl bm bn bo bp bq br bs bt bu bv bw bx by bz ca cb cc cd ce cf cg ch ci cj ck cl cm cn co cp cq cr cs ct cu cv cw cx cy cz da db dc dd de df dg dh di dj dk dl dm dn do dp dq dr ds dt du dv dw dx dy dz ea eb ec ed ee ef eg eh ei ej ek el em en eo ep eq er es et eu ev ew ex ey ez fa fb fc fd fe ff fg fh fi fj fk fl fm fn fo fp fq fr fs ft fu fv fw fx fy fz ga gb gc gd ge gf gg gh gi gj gk gl gm gn go gp gq gr gs gt gu gv gw gx gy gz ha hb hc hd he hf hg hh hi hj hk hl hm hn ho hp hq hr hs ht hu hv hw hx hy hz ia ib ic id ie if ig ih ii ij ik il im in io ip iq ir is it iu iv iw ix iy iz ja jb jc jd je jf jg jh ji jj jk jl jm jn jo jp jq jr js jt ju jv jw jx jy jz ka kb kc kd ke kf kg kh ki kj kk kl km kn ko kp kq kr ks kt ku kv kw kx ky kz la lb lc ld le lf lg lh li lj lk ll lm ln lo lp lq lr ls lt lu lv lw lx ly lz ma mb mc md me mf mg mh mi mj mk ml mm mn mo mp mq mr ms mt mu mv mw mx my mz na nb nc nd ne nf ng nh ni nj nk nl nm nn no np nq nr ns nt nu nv nw nx ny nz oa ob oc od oe of og oh oi oj ok ol om on oo op oq or os ot ou ov ow ox oy oz pa pb pc pd pe pf pg ph pi pj pk pl pm pn po pp pq pr ps pt pu pv pw px py pz qa qb qc qd qe qf qg qh qi qj qk ql qm qn qo qp qq qr qs qt qu qv qw qx qy qz ra rb rc rd re rf rg rh ri rj rk rl rm rn ro rp rq rr rs rt ru rv rw rx ry rz sa sb sc sd se sf sg sh si sj sk sl sm sn so sp sq sr ss st su sv sw sx sy sz ta tb tc td te tf tg th ti tj tk tl tm tn to tp tq tr ts tt tu tv tw tx ty tz ua ub uc ud ue uf ug uh ui uj uk ul um un uo up uq ur us ut uu uv uw ux uy uz va vb vc vd ve vf vg vh vi vj vk vl vm vn vo vp vq vr vs vt vu vv vw vx vy vz wa wb wc wd we wf wg wh wi wj wk wl wm wn wo wp wq wr ws wt wu wv ww wx wy wz xa xb xc xd xe xf xg xh xi xj xk xl xm xn xo xp xq xr xs xt xu xv xw xx xy xz ya yb yc yd ye yf yg yh yi yj yk yl ym yn yo yp yq yr ys yt yu yv yw yx yy yz za zb zc zd ze zf zg zh zi zj zk zl zm zn zo zp zq zr zs zt zu zv zw zx zy zz aaa aab aac aad aae aaf aag aah aai aaj aak aal aam aan aao aap aaq aar aas aat aau aav aaw aax aay aaz aba abb abc abd abe abf abg abh abi abj abk abl abm abn abo abp abq abr abs abt abu abv abw abx aby abz aca acb acc acd ace acf acg ach aci acj ack acl acm acn aco acp acq acr acs act acu acv acw acx acy acz ada adb adc add ade adf adg adh adi adj adk adl adm adn ado adp adq adr ads adt adu adv adw adx ady adz aea aeb aec aed aee aef aeg aeh aei aej aek ael aem aen aeo aep aeq aer aes aet aeu aev aew aex aey aez afa afb afc afd afe aff afg afh afi afj afk afl afm afn afo afp afq afr afs aft afu afv afw afx afy afz aga agb agc agd age agf agg agh agi agj agk agl agm agn ago agp agq agr ags agt agu agv agw agx agy agz aha ahb ahc ahd ahe ahf ahg ahh ahi ahj ahk ahl ahm ahn aho ahp ahq ahr ahs aht ahu ahv ahw ahx ahy ahz aia aib aic aid aie aif aig aih aii aij aik ail aim ain aio aip aiq air ais ait aiu aiv aiw aix aiy aiz aja ajb ajc ajd aje ajf ajg ajh aji ajj ajk ajl ajm ajn ajo ajp ajq ajr ajs ajt aju ajv ajw ajx ajy ajz aka akb akc akd ake akf akg akh aki akj akk akl akm akn ako akp akq akr aks akt aku akv akw akx aky akz ala alb alc ald ale alf alg alh ali alj alk all alm aln alo alp alq alr als alt alu alv alw alx aly alz ama amb amc amd ame amf amg amh ami amj amk aml amm amn amo amp amq amr ams amt amu amv amw amx amy amz ana anb anc and ane anf ang anh ani anj ank anl anm ann ano anp anq anr ans ant anu anv anw anx any anz aoa aob aoc aod aoe aof aog aoh aoi aoj aok aol aom aon aoo aop aoq aor aos aot aou aov aow aox aoy aoz apa apb apc apd ape apf apg aph api apj apk apl apm apn apo app apq apr aps apt apu apv apw apx apy apz aqa aqb aqc aqd aqe aqf aqg aqh aqi aqj aqk aql aqm aqn aqo aqp aqq aqr aqs aqt aqu aqv aqw aqx aqy aqz ara arb arc ard are arf arg arh ari arj ark arl arm arn aro arp arq arr ars art aru arv arw arx ary arz asa asb asc asd ase asf asg ash asi asj ask asl asm asn aso asp asq asr ass ast asu asv asw asx asy asz ata atb atc atd ate atf atg ath ati atj atk atl atm atn ato atp atq atr ats att atu atv atw atx aty atz aua aub auc aud aue auf aug auh aui auj auk aul aum aun auo aup auq aur aus aut auu auv auw aux auy auz ava avb avc avd ave avf avg avh avi avj avk avl avm avn avo avp avq avr avs avt avu avv avw avx avy avz awa awb awc awd awe awf awg awh awi awj awk awl awm awn awo awp awq awr aws awt awu awv aww awx awy awz axa axb axc axd axe axf axg axh axi axj axk axl axm axn axo axp axq axr axs axt axu axv axw axx axy axz aya ayb ayc ayd aye ayf ayg ayh ayi ayj ayk ayl aym ayn ayo ayp ayq ayr ays ayt ayu ayv ayw ayx ayy ayz aza azb azc azd aze azf azg azh azi azj azk azl azm azn azo azp azq azr azs azt azu azv azw azx azy azz

Catan-gen

2022-11-20T12:45:58Z

Link: /* Notes */

{{lowercase}}
'''catan-gen''' is a fully convergent map creation app for [https://www.catan.com/ Catan]. It is written in <code>C++</code> and uses <code>libadwaita</code> to provide a UX that is friendly on both desktop and mobile devices.

=Dependencies=
* Unix-like system (tested: Gentoo, Mobian on PinePhone, Mac OS Monterrey)
* [https://www.gtk.org/ GTK4] >= 4.6.0
* [https://gitlab.gnome.org/GNOME/libadwaita libadwaita] >= 1.0.0
* [https://eigen.tuxfamily.org/index.php?title=Main_Page Eigen] >= 3.4
* [https://www.cairographics.org/ Cairo] >= 1.14
* [https://github.com/open-source-parsers/jsoncpp jsoncpp] >= 1.9
* [https://www.boost.org/ Boost] > 1.74
* [https://github.com/fmtlib/fmt fmt] > 8.1.0 (as of catan-gen 0.2)

=Obtaining catan-gen=
catan-gen is available as a source tarball at http://proj.penguindevelopment.org/catan-gen/. [http://proj.penguindevelopment.org/catan-gen/catan-gen-latest.tar.gz Direct link to the latest version.]

Installation follows the usual configure/make/make install procedure.

=Using catan-gen=
'''N.B. these instructions apply to version 0.1. As of version 0.2, there are some (initially disabled) UI elements on the startup screen that allow growing/shrinking and/or wiping an existing map.'''

Upon launching catan-gen, you will be presented with a simple UI:

[[File:Catan-gen-ui-firstopen.png]]

No map has been generated yet, since the app obviously can't divine what size of map you want; you can set that on this page. A radius of 0 corresponds to a single tile, a radius of 1 adds the 6 nearest-neighbour tiles around it, and so on. Press the Generate button and enlarge the window to find a map filled with water:

[[File:Catan-gen-blank-map.png]]

Before going into the details, let's have a look at the toolbar:

[[File:Catan-gen-toolbar.png]]

From left to right, these buttons are ''zoom out'', ''zoom in'', ''terrain paint mode'', ''paint tile type'', ''roll tile types'', ''roll numbers'', ''clear numbers'' and ''clear tile types''. The zoom buttons are self-explanatory. ''Terrain paint mode'' is a toggle button, and is enabled by default. In this mode, you can draw land areas directly onto your map, simply by pressinging the tiles. ''Paint tile type'' (the downwards arrow) lets you choose ''what'' to draw, and is set to "Unspecified" by default. Press a few tiles to draw your map:

[[File:Catan-gen-unspecified-paint.png]]

If you want to switch a tile back to water, simply press it again. Once you're satisfied with the shape of your map, it is time to roll tile types, which changes the unspecified tiles into resources. But before you press ''roll tile types'', press the ''Tileset'' button in the titlebar. The page that appears allows you specify how many tiles of each resource you want to generate.

[[File:Catan-gen-tileset.png]]

For each resource, you can specify the minimum and maximum number of tiles you want to have. The current number is also listed. Colour-blind users may also want to adjust the colour of each tile type. (N.B. this list can scroll; on desktops, use the mouse scroll wheel or the scrollbar that appears when hovering; on touchscreen devices, just drag to scroll.) When you are satisfied, go back to the map page and press the ''roll tile type'' button (the die) to populate your map:

[[File:Catan-gen-fill-tiles.png]]

If you don't have enough unspecified tiles to satisfy the minimum tile amounts listed on the tileset page, you will be met with an error instead. If you are unhappy with the generated map, you can still freely change the tiles by pressing them. Alternatively, you can press ''clear tile types'' to wipe every resource back to unspecified (N.B. this includes tiles you have manually set, so be careful with this button). Next, you can auto-generate the numbers that go on each resource, simply by pressing ''roll numbers'' (the circled 8).

[[File:Catan-gen-fill-numbers.png]]

''Clear numbers'' removes them again, if you are unhappy. If you want to change a single number, you will need to turn off terrain paint mode. Once turned off, pressing a tile will open an overlay that lets you set the type and number directly:

[[File:Catan-gen-tile-overlay.png]]

(Note that the clicked tile has been highlighted in green.) Press the checkmark button on the right-hand side to accept the changes, or the cross on the left-hand side to discard them.

'''NOTE: unfortunately, selecting tile types and numbers from this interface can be unreliable due to [https://gitlab.gnome.org/GNOME/gtk/-/issues/2877 GTK bug 2877]. If the app refuses to accept your selection, you can use the keyboard to navigate to the drop-down and select an entry. Sadly, this does not appear to work with Squeekboard, so you will need a physical (Bluetooth or USB) keyboard on Phosh-based devices.'''

When you are completely satisfied with your map, you can export it from the hamburger menu (top-left corner). "Export SVG" produces a vector graphic representation identical to the one you see on-screen. "Export JSON" produces a textual representation of the map, which can be reimported at a later time. Of course, you can also generate a new map, which brings you back to the startup view.

=Notes=
Although catan-gen currently suffices at basic mapping, some new features are currently planned, namely '''custom tile types''' (which would include the ability to import and export the tile set via JSON) and '''automatic generation''' of a map outline, which would most likely also incorporate the placement of '''harbours'''.

Currently, generated maps are always hexagonal, which can waste large swaths of space if a different shape is required. It is already possible to manually create non-hexagonal maps by importing a JSON file as a template, e.g. by exporting a blank hexagonal map and editing the JSON file to remove unwanted tiles. However, this is subject to an important symmetry constraint: ''the centre of the map must correspond to the centre of tile (0, 0)''. Failure to meet this requirement currently makes it impossible to correctly interpret mouse clicks/finger taps on the map. Since this is not trivial to resolve and the work-around is inconvenient but not prohibitively complicated, generating non-hexagonal maps most likely will not be supported from within the app.

==Bugs and feedback==
{{bugs and feedback}}

[[Category:Software]]

Catan-gen

2022-11-20T12:41:48Z

Link: /* Using catan-gen */

{{lowercase}}
'''catan-gen''' is a fully convergent map creation app for [https://www.catan.com/ Catan]. It is written in <code>C++</code> and uses <code>libadwaita</code> to provide a UX that is friendly on both desktop and mobile devices.

=Dependencies=
* Unix-like system (tested: Gentoo, Mobian on PinePhone, Mac OS Monterrey)
* [https://www.gtk.org/ GTK4] >= 4.6.0
* [https://gitlab.gnome.org/GNOME/libadwaita libadwaita] >= 1.0.0
* [https://eigen.tuxfamily.org/index.php?title=Main_Page Eigen] >= 3.4
* [https://www.cairographics.org/ Cairo] >= 1.14
* [https://github.com/open-source-parsers/jsoncpp jsoncpp] >= 1.9
* [https://www.boost.org/ Boost] > 1.74
* [https://github.com/fmtlib/fmt fmt] > 8.1.0 (as of catan-gen 0.2)

=Obtaining catan-gen=
catan-gen is available as a source tarball at http://proj.penguindevelopment.org/catan-gen/. [http://proj.penguindevelopment.org/catan-gen/catan-gen-latest.tar.gz Direct link to the latest version.]

Installation follows the usual configure/make/make install procedure.

=Using catan-gen=
'''N.B. these instructions apply to version 0.1. As of version 0.2, there are some (initially disabled) UI elements on the startup screen that allow growing/shrinking and/or wiping an existing map.'''

Upon launching catan-gen, you will be presented with a simple UI:

[[File:Catan-gen-ui-firstopen.png]]

No map has been generated yet, since the app obviously can't divine what size of map you want; you can set that on this page. A radius of 0 corresponds to a single tile, a radius of 1 adds the 6 nearest-neighbour tiles around it, and so on. Press the Generate button and enlarge the window to find a map filled with water:

[[File:Catan-gen-blank-map.png]]

Before going into the details, let's have a look at the toolbar:

[[File:Catan-gen-toolbar.png]]

From left to right, these buttons are ''zoom out'', ''zoom in'', ''terrain paint mode'', ''paint tile type'', ''roll tile types'', ''roll numbers'', ''clear numbers'' and ''clear tile types''. The zoom buttons are self-explanatory. ''Terrain paint mode'' is a toggle button, and is enabled by default. In this mode, you can draw land areas directly onto your map, simply by pressinging the tiles. ''Paint tile type'' (the downwards arrow) lets you choose ''what'' to draw, and is set to "Unspecified" by default. Press a few tiles to draw your map:

[[File:Catan-gen-unspecified-paint.png]]

If you want to switch a tile back to water, simply press it again. Once you're satisfied with the shape of your map, it is time to roll tile types, which changes the unspecified tiles into resources. But before you press ''roll tile types'', press the ''Tileset'' button in the titlebar. The page that appears allows you specify how many tiles of each resource you want to generate.

[[File:Catan-gen-tileset.png]]

For each resource, you can specify the minimum and maximum number of tiles you want to have. The current number is also listed. Colour-blind users may also want to adjust the colour of each tile type. (N.B. this list can scroll; on desktops, use the mouse scroll wheel or the scrollbar that appears when hovering; on touchscreen devices, just drag to scroll.) When you are satisfied, go back to the map page and press the ''roll tile type'' button (the die) to populate your map:

[[File:Catan-gen-fill-tiles.png]]

If you don't have enough unspecified tiles to satisfy the minimum tile amounts listed on the tileset page, you will be met with an error instead. If you are unhappy with the generated map, you can still freely change the tiles by pressing them. Alternatively, you can press ''clear tile types'' to wipe every resource back to unspecified (N.B. this includes tiles you have manually set, so be careful with this button). Next, you can auto-generate the numbers that go on each resource, simply by pressing ''roll numbers'' (the circled 8).

[[File:Catan-gen-fill-numbers.png]]

''Clear numbers'' removes them again, if you are unhappy. If you want to change a single number, you will need to turn off terrain paint mode. Once turned off, pressing a tile will open an overlay that lets you set the type and number directly:

[[File:Catan-gen-tile-overlay.png]]

(Note that the clicked tile has been highlighted in green.) Press the checkmark button on the right-hand side to accept the changes, or the cross on the left-hand side to discard them.

'''NOTE: unfortunately, selecting tile types and numbers from this interface can be unreliable due to [https://gitlab.gnome.org/GNOME/gtk/-/issues/2877 GTK bug 2877]. If the app refuses to accept your selection, you can use the keyboard to navigate to the drop-down and select an entry. Sadly, this does not appear to work with Squeekboard, so you will need a physical (Bluetooth or USB) keyboard on Phosh-based devices.'''

When you are completely satisfied with your map, you can export it from the hamburger menu (top-left corner). "Export SVG" produces a vector graphic representation identical to the one you see on-screen. "Export JSON" produces a textual representation of the map, which can be reimported at a later time. Of course, you can also generate a new map, which brings you back to the startup view.

=Notes=
Although catan-gen currently suffices at basic mapping, some new features are currently planned. '''Internationalisation''' will be relatively simple to add to the app as-is. A more complex feature --- the most complex one currently planned --- is the support of '''custom tile types''', which would include the ability to import and export the tile set via JSON.

Currently, generated maps are always hexagonal, which can waste large swaths of space if a different shape is required. It is already possible to manually create non-hexagonal maps by importing a JSON file as a template, e.g. by exporting a blank hexagonal map and editing the JSON file to remove unwanted tiles. However, this is subject to an important symmetry constraint: ''the centre of the map must correspond to the centre of tile (0, 0)''. Failure to meet this requirement currently makes it impossible to correctly interpret mouse clicks/finger taps on the map. Since this is not trivial to resolve and the work-around is inconvenient but not prohibitively complicated, generating non-hexagonal maps most likely will not be supported from within the app.

Allowing the map to be '''extended''' or '''shrunk''' without discarding it completely is relatively simple and will most likely be included in the next non-bugfix update.

'''Automatic generation''' of a map outline is the final complex feature currently planned. This would most likely also incorporate the placement of '''harbours''', which are not currently included.

==Bugs and feedback==
{{bugs and feedback}}

[[Category:Software]]

Catan-gen

2022-11-20T12:37:46Z

Link: /* Dependencies */

{{lowercase}}
'''catan-gen''' is a fully convergent map creation app for [https://www.catan.com/ Catan]. It is written in <code>C++</code> and uses <code>libadwaita</code> to provide a UX that is friendly on both desktop and mobile devices.

=Dependencies=
* Unix-like system (tested: Gentoo, Mobian on PinePhone, Mac OS Monterrey)
* [https://www.gtk.org/ GTK4] >= 4.6.0
* [https://gitlab.gnome.org/GNOME/libadwaita libadwaita] >= 1.0.0
* [https://eigen.tuxfamily.org/index.php?title=Main_Page Eigen] >= 3.4
* [https://www.cairographics.org/ Cairo] >= 1.14
* [https://github.com/open-source-parsers/jsoncpp jsoncpp] >= 1.9
* [https://www.boost.org/ Boost] > 1.74
* [https://github.com/fmtlib/fmt fmt] > 8.1.0 (as of catan-gen 0.2)

=Obtaining catan-gen=
catan-gen is available as a source tarball at http://proj.penguindevelopment.org/catan-gen/. [http://proj.penguindevelopment.org/catan-gen/catan-gen-latest.tar.gz Direct link to the latest version.]

Installation follows the usual configure/make/make install procedure.

=Using catan-gen=
Upon launching catan-gen, you will be presented with a simple UI:

[[File:Catan-gen-ui-firstopen.png]]

No map has been generated yet, since the app obviously can't divine what size of map you want; you can set that on this page. A radius of 0 corresponds to a single tile, a radius of 1 adds the 6 nearest-neighbour tiles around it, and so on. Press the Generate button and enlarge the window to find a map filled with water:

[[File:Catan-gen-blank-map.png]]

Before going into the details, let's have a look at the toolbar:

[[File:Catan-gen-toolbar.png]]

From left to right, these buttons are ''zoom out'', ''zoom in'', ''terrain paint mode'', ''paint tile type'', ''roll tile types'', ''roll numbers'', ''clear numbers'' and ''clear tile types''. The zoom buttons are self-explanatory. ''Terrain paint mode'' is a toggle button, and is enabled by default. In this mode, you can draw land areas directly onto your map, simply by pressinging the tiles. ''Paint tile type'' (the downwards arrow) lets you choose ''what'' to draw, and is set to "Unspecified" by default. Press a few tiles to draw your map:

[[File:Catan-gen-unspecified-paint.png]]

If you want to switch a tile back to water, simply press it again. Once you're satisfied with the shape of your map, it is time to roll tile types, which changes the unspecified tiles into resources. But before you press ''roll tile types'', press the ''Tileset'' button in the titlebar. The page that appears allows you specify how many tiles of each resource you want to generate.

[[File:Catan-gen-tileset.png]]

For each resource, you can specify the minimum and maximum number of tiles you want to have. The current number is also listed. Colour-blind users may also want to adjust the colour of each tile type. (N.B. this list can scroll; on desktops, use the mouse scroll wheel or the scrollbar that appears when hovering; on touchscreen devices, just drag to scroll.) When you are satisfied, go back to the map page and press the ''roll tile type'' button (the die) to populate your map:

[[File:Catan-gen-fill-tiles.png]]

If you don't have enough unspecified tiles to satisfy the minimum tile amounts listed on the tileset page, you will be met with an error instead. If you are unhappy with the generated map, you can still freely change the tiles by pressing them. Alternatively, you can press ''clear tile types'' to wipe every resource back to unspecified (N.B. this includes tiles you have manually set, so be careful with this button). Next, you can auto-generate the numbers that go on each resource, simply by pressing ''roll numbers'' (the circled 8).

[[File:Catan-gen-fill-numbers.png]]

''Clear numbers'' removes them again, if you are unhappy. If you want to change a single number, you will need to turn off terrain paint mode. Once turned off, pressing a tile will open an overlay that lets you set the type and number directly:

[[File:Catan-gen-tile-overlay.png]]

(Note that the clicked tile has been highlighted in green.) Press the checkmark button on the right-hand side to accept the changes, or the cross on the left-hand side to discard them.

'''NOTE: unfortunately, selecting tile types and numbers from this interface can be unreliable due to [https://gitlab.gnome.org/GNOME/gtk/-/issues/2877 GTK bug 2877]. If the app refuses to accept your selection, you can use the keyboard to navigate to the drop-down and select an entry. Sadly, this does not appear to work with Squeekboard, so you will need a physical (Bluetooth or USB) keyboard on Phosh-based devices.'''

When you are completely satisfied with your map, you can export it from the hamburger menu (top-left corner). "Export SVG" produces a vector graphic representation identical to the one you see on-screen. "Export JSON" produces a textual representation of the map, which can be reimported at a later time. Of course, you can also generate a new map, which brings you back to the startup view.

=Notes=
Although catan-gen currently suffices at basic mapping, some new features are currently planned. '''Internationalisation''' will be relatively simple to add to the app as-is. A more complex feature --- the most complex one currently planned --- is the support of '''custom tile types''', which would include the ability to import and export the tile set via JSON.

Currently, generated maps are always hexagonal, which can waste large swaths of space if a different shape is required. It is already possible to manually create non-hexagonal maps by importing a JSON file as a template, e.g. by exporting a blank hexagonal map and editing the JSON file to remove unwanted tiles. However, this is subject to an important symmetry constraint: ''the centre of the map must correspond to the centre of tile (0, 0)''. Failure to meet this requirement currently makes it impossible to correctly interpret mouse clicks/finger taps on the map. Since this is not trivial to resolve and the work-around is inconvenient but not prohibitively complicated, generating non-hexagonal maps most likely will not be supported from within the app.

Allowing the map to be '''extended''' or '''shrunk''' without discarding it completely is relatively simple and will most likely be included in the next non-bugfix update.

'''Automatic generation''' of a map outline is the final complex feature currently planned. This would most likely also incorporate the placement of '''harbours''', which are not currently included.

==Bugs and feedback==
{{bugs and feedback}}

[[Category:Software]]

Catan-gen

2022-08-09T11:59:33Z

Link: /* Dependencies */

{{lowercase}}
'''catan-gen''' is a fully convergent map creation app for [https://www.catan.com/ Catan]. It is written in <code>C++</code> and uses <code>libadwaita</code> to provide a UX that is friendly on both desktop and mobile devices.

=Dependencies=
* Unix-like system (tested: Gentoo, Mobian on PinePhone, Mac OS Monterrey)
* [https://www.gtk.org/ GTK4] >= 4.6.0
* [https://gitlab.gnome.org/GNOME/libadwaita libadwaita] >= 1.0.0
* [https://eigen.tuxfamily.org/index.php?title=Main_Page Eigen] >= 3.4
* [https://www.cairographics.org/ Cairo] >= 1.14
* [https://github.com/open-source-parsers/jsoncpp jsoncpp] >= 1.9
* [https://www.boost.org/ Boost] > 1.74

=Obtaining catan-gen=
catan-gen is available as a source tarball at http://proj.penguindevelopment.org/catan-gen/. [http://proj.penguindevelopment.org/catan-gen/catan-gen-latest.tar.gz Direct link to the latest version.]

Installation follows the usual configure/make/make install procedure.

=Using catan-gen=
Upon launching catan-gen, you will be presented with a simple UI:

[[File:Catan-gen-ui-firstopen.png]]

No map has been generated yet, since the app obviously can't divine what size of map you want; you can set that on this page. A radius of 0 corresponds to a single tile, a radius of 1 adds the 6 nearest-neighbour tiles around it, and so on. Press the Generate button and enlarge the window to find a map filled with water:

[[File:Catan-gen-blank-map.png]]

Before going into the details, let's have a look at the toolbar:

[[File:Catan-gen-toolbar.png]]

From left to right, these buttons are ''zoom out'', ''zoom in'', ''terrain paint mode'', ''paint tile type'', ''roll tile types'', ''roll numbers'', ''clear numbers'' and ''clear tile types''. The zoom buttons are self-explanatory. ''Terrain paint mode'' is a toggle button, and is enabled by default. In this mode, you can draw land areas directly onto your map, simply by pressinging the tiles. ''Paint tile type'' (the downwards arrow) lets you choose ''what'' to draw, and is set to "Unspecified" by default. Press a few tiles to draw your map:

[[File:Catan-gen-unspecified-paint.png]]

If you want to switch a tile back to water, simply press it again. Once you're satisfied with the shape of your map, it is time to roll tile types, which changes the unspecified tiles into resources. But before you press ''roll tile types'', press the ''Tileset'' button in the titlebar. The page that appears allows you specify how many tiles of each resource you want to generate.

[[File:Catan-gen-tileset.png]]

For each resource, you can specify the minimum and maximum number of tiles you want to have. The current number is also listed. Colour-blind users may also want to adjust the colour of each tile type. (N.B. this list can scroll; on desktops, use the mouse scroll wheel or the scrollbar that appears when hovering; on touchscreen devices, just drag to scroll.) When you are satisfied, go back to the map page and press the ''roll tile type'' button (the die) to populate your map:

[[File:Catan-gen-fill-tiles.png]]

If you don't have enough unspecified tiles to satisfy the minimum tile amounts listed on the tileset page, you will be met with an error instead. If you are unhappy with the generated map, you can still freely change the tiles by pressing them. Alternatively, you can press ''clear tile types'' to wipe every resource back to unspecified (N.B. this includes tiles you have manually set, so be careful with this button). Next, you can auto-generate the numbers that go on each resource, simply by pressing ''roll numbers'' (the circled 8).

[[File:Catan-gen-fill-numbers.png]]

''Clear numbers'' removes them again, if you are unhappy. If you want to change a single number, you will need to turn off terrain paint mode. Once turned off, pressing a tile will open an overlay that lets you set the type and number directly:

[[File:Catan-gen-tile-overlay.png]]

(Note that the clicked tile has been highlighted in green.) Press the checkmark button on the right-hand side to accept the changes, or the cross on the left-hand side to discard them.

'''NOTE: unfortunately, selecting tile types and numbers from this interface can be unreliable due to [https://gitlab.gnome.org/GNOME/gtk/-/issues/2877 GTK bug 2877]. If the app refuses to accept your selection, you can use the keyboard to navigate to the drop-down and select an entry. Sadly, this does not appear to work with Squeekboard, so you will need a physical (Bluetooth or USB) keyboard on Phosh-based devices.'''

When you are completely satisfied with your map, you can export it from the hamburger menu (top-left corner). "Export SVG" produces a vector graphic representation identical to the one you see on-screen. "Export JSON" produces a textual representation of the map, which can be reimported at a later time. Of course, you can also generate a new map, which brings you back to the startup view.

=Notes=
Although catan-gen currently suffices at basic mapping, some new features are currently planned. '''Internationalisation''' will be relatively simple to add to the app as-is. A more complex feature --- the most complex one currently planned --- is the support of '''custom tile types''', which would include the ability to import and export the tile set via JSON.

Currently, generated maps are always hexagonal, which can waste large swaths of space if a different shape is required. It is already possible to manually create non-hexagonal maps by importing a JSON file as a template, e.g. by exporting a blank hexagonal map and editing the JSON file to remove unwanted tiles. However, this is subject to an important symmetry constraint: ''the centre of the map must correspond to the centre of tile (0, 0)''. Failure to meet this requirement currently makes it impossible to correctly interpret mouse clicks/finger taps on the map. Since this is not trivial to resolve and the work-around is inconvenient but not prohibitively complicated, generating non-hexagonal maps most likely will not be supported from within the app.

Allowing the map to be '''extended''' or '''shrunk''' without discarding it completely is relatively simple and will most likely be included in the next non-bugfix update.

'''Automatic generation''' of a map outline is the final complex feature currently planned. This would most likely also incorporate the placement of '''harbours''', which are not currently included.

==Bugs and feedback==
{{bugs and feedback}}

[[Category:Software]]

Main Page

2022-08-06T11:16:55Z

Link:

Welcome to '''Penguin Development'''! We make [[w:free and open-source software|free and open-source software]] and [[w:Open-source hardware|hardware]].

See below for current releases. All software and hardware is licensed under the [https://gnu.org/licenses/gpl.html GPL] (version 3 or higher) unless otherwise stated.

=Software=
* [[AUTOMOME]] — the OTTish AUTOMEME clone
* [[Ising]] — Monte Carlo Ising model simulator
* [[stackermann]] — a stack-based [[w:Ackermann function|Ackermann function]] calculator
* [[catan-gen]] — convergent map creation app for [https://www.catan.com/ Catan]

=Hardware=
* [[timelapse]] — time-lapse trigger for digital cameras

=Code snippets and how-tos=
* [[Animated 3D plotting with Blender]]
* [[Matrix Synapse and mautrix-whatsapp in a VPN]]

Main Page

2022-08-06T11:16:35Z

Link: /* Software */

Welcome to '''Penguin Development'''! We make [[w:free and open-source software|free and open-source software]] and [[w:Open-source hardware|hardware]].

See below for current releases. All software and hardware is licensed under the [https://gnu.org/licenses/gpl.html GPL] (version 3 or higher) unless otherwise stated.

=Software=
* [[AUTOMOME]] — the OTTish AUTOMEME clone
* [[Ising]] — Monte Carlo Ising model simulator
* [[stackermann]] — a stack-based [[w:Ackermann function|Ackermann function]] calculator
* [[catan-gen]] — convergent map creation app for [https://www.catan.com/ Catan]

=Hardware=
* [[timelapse]] — time-lapse trigger for digital cameras

=Code snippets and how-tos=
* [[Animated 3D plotting with Blender]]
* [[Matrix Synapse and mautrix-whatsapp in a VPN]]

=Other=
* [[LineageOS builds|Unofficial LineageOS builds]]

Catan-gen

2022-08-06T11:15:29Z

Link: Created page with "{{lowercase}} '''catan-gen''' is a fully convergent map creation app for [https://www.catan.com/ Catan]. It is written in <code>C++</code> and uses <code>libadwaita</code> to..."

{{lowercase}}
'''catan-gen''' is a fully convergent map creation app for [https://www.catan.com/ Catan]. It is written in <code>C++</code> and uses <code>libadwaita</code> to provide a UX that is friendly on both desktop and mobile devices.

=Dependencies=
* Unix-like system (tested: Gentoo, Mobian on PinePhone, Mac OS X)
* [https://www.gtk.org/ GTK4] >= 4.6.0
* [https://gitlab.gnome.org/GNOME/libadwaita libadwaita] >= 1.0.0
* [https://eigen.tuxfamily.org/index.php?title=Main_Page Eigen] >= 3.4
* [https://www.cairographics.org/ Cairo] >= 1.14
* [https://github.com/open-source-parsers/jsoncpp jsoncpp] >= 1.9
* [https://www.boost.org/ Boost] > 1.74

=Obtaining catan-gen=
catan-gen is available as a source tarball at http://proj.penguindevelopment.org/catan-gen/. [http://proj.penguindevelopment.org/catan-gen/catan-gen-latest.tar.gz Direct link to the latest version.]

Installation follows the usual configure/make/make install procedure.

=Using catan-gen=
Upon launching catan-gen, you will be presented with a simple UI:

[[File:Catan-gen-ui-firstopen.png]]

No map has been generated yet, since the app obviously can't divine what size of map you want; you can set that on this page. A radius of 0 corresponds to a single tile, a radius of 1 adds the 6 nearest-neighbour tiles around it, and so on. Press the Generate button and enlarge the window to find a map filled with water:

[[File:Catan-gen-blank-map.png]]

Before going into the details, let's have a look at the toolbar:

[[File:Catan-gen-toolbar.png]]

From left to right, these buttons are ''zoom out'', ''zoom in'', ''terrain paint mode'', ''paint tile type'', ''roll tile types'', ''roll numbers'', ''clear numbers'' and ''clear tile types''. The zoom buttons are self-explanatory. ''Terrain paint mode'' is a toggle button, and is enabled by default. In this mode, you can draw land areas directly onto your map, simply by pressinging the tiles. ''Paint tile type'' (the downwards arrow) lets you choose ''what'' to draw, and is set to "Unspecified" by default. Press a few tiles to draw your map:

[[File:Catan-gen-unspecified-paint.png]]

If you want to switch a tile back to water, simply press it again. Once you're satisfied with the shape of your map, it is time to roll tile types, which changes the unspecified tiles into resources. But before you press ''roll tile types'', press the ''Tileset'' button in the titlebar. The page that appears allows you specify how many tiles of each resource you want to generate.

[[File:Catan-gen-tileset.png]]

For each resource, you can specify the minimum and maximum number of tiles you want to have. The current number is also listed. Colour-blind users may also want to adjust the colour of each tile type. (N.B. this list can scroll; on desktops, use the mouse scroll wheel or the scrollbar that appears when hovering; on touchscreen devices, just drag to scroll.) When you are satisfied, go back to the map page and press the ''roll tile type'' button (the die) to populate your map:

[[File:Catan-gen-fill-tiles.png]]

If you don't have enough unspecified tiles to satisfy the minimum tile amounts listed on the tileset page, you will be met with an error instead. If you are unhappy with the generated map, you can still freely change the tiles by pressing them. Alternatively, you can press ''clear tile types'' to wipe every resource back to unspecified (N.B. this includes tiles you have manually set, so be careful with this button). Next, you can auto-generate the numbers that go on each resource, simply by pressing ''roll numbers'' (the circled 8).

[[File:Catan-gen-fill-numbers.png]]

''Clear numbers'' removes them again, if you are unhappy. If you want to change a single number, you will need to turn off terrain paint mode. Once turned off, pressing a tile will open an overlay that lets you set the type and number directly:

[[File:Catan-gen-tile-overlay.png]]

(Note that the clicked tile has been highlighted in green.) Press the checkmark button on the right-hand side to accept the changes, or the cross on the left-hand side to discard them.

'''NOTE: unfortunately, selecting tile types and numbers from this interface can be unreliable due to [https://gitlab.gnome.org/GNOME/gtk/-/issues/2877 GTK bug 2877]. If the app refuses to accept your selection, you can use the keyboard to navigate to the drop-down and select an entry. Sadly, this does not appear to work with Squeekboard, so you will need a physical (Bluetooth or USB) keyboard on Phosh-based devices.'''

When you are completely satisfied with your map, you can export it from the hamburger menu (top-left corner). "Export SVG" produces a vector graphic representation identical to the one you see on-screen. "Export JSON" produces a textual representation of the map, which can be reimported at a later time. Of course, you can also generate a new map, which brings you back to the startup view.

=Notes=
Although catan-gen currently suffices at basic mapping, some new features are currently planned. '''Internationalisation''' will be relatively simple to add to the app as-is. A more complex feature --- the most complex one currently planned --- is the support of '''custom tile types''', which would include the ability to import and export the tile set via JSON.

Currently, generated maps are always hexagonal, which can waste large swaths of space if a different shape is required. It is already possible to manually create non-hexagonal maps by importing a JSON file as a template, e.g. by exporting a blank hexagonal map and editing the JSON file to remove unwanted tiles. However, this is subject to an important symmetry constraint: ''the centre of the map must correspond to the centre of tile (0, 0)''. Failure to meet this requirement currently makes it impossible to correctly interpret mouse clicks/finger taps on the map. Since this is not trivial to resolve and the work-around is inconvenient but not prohibitively complicated, generating non-hexagonal maps most likely will not be supported from within the app.

Allowing the map to be '''extended''' or '''shrunk''' without discarding it completely is relatively simple and will most likely be included in the next non-bugfix update.

'''Automatic generation''' of a map outline is the final complex feature currently planned. This would most likely also incorporate the placement of '''harbours''', which are not currently included.

==Bugs and feedback==
{{bugs and feedback}}

[[Category:Software]]

Template:Bugs and feedback

2022-08-06T11:13:36Z

Link:

Report bugs via email at <tt>bugs[at]proj[dot]penguindevelopment[dot]org</tt>.

Send your feedback to <tt>feedback[at]proj[dot]penguindevelopment[dot]org</tt>.

File:Catan-gen-toolbar.png

2022-08-06T09:36:15Z

Link: Toolbar in catan-gen.

== Summary ==
Toolbar in catan-gen.

File:Catan-gen-unspecified-paint.png

2022-08-06T09:08:57Z

Link: Map with unspecified tiles in catan-gen.

== Summary ==
Map with unspecified tiles in catan-gen.

File:Catan-gen-tileset.png

2022-08-06T09:08:21Z

Link: Tileset page in catan-gen.

== Summary ==
Tileset page in catan-gen.

File:Catan-gen-tile-overlay.png

2022-08-06T09:07:46Z

Link: Active tile overlay in catan-gen.

== Summary ==
Active tile overlay in catan-gen.

File:Catan-gen-fill-tiles.png

2022-08-06T09:06:16Z

Link: Map with unnumbered resource tiles in catan-gen.

== Summary ==
Map with unnumbered resource tiles in catan-gen.

File:Catan-gen-fill-numbers.png

2022-08-06T09:05:41Z

Link: Map filled with numbered resources in catan-gen.

== Summary ==
Map filled with numbered resources in catan-gen.

File:Catan-gen-blank-map.png

2022-08-06T09:04:30Z

Link: Blank map in catan-gen.

== Summary ==
Blank map in catan-gen.

File:Catan-gen-ui-firstopen.png

2022-08-06T09:03:56Z

Link: UI when opening catan-gen.

== Summary ==
UI when opening catan-gen.

Matrix Synapse and mautrix-whatsapp in a VPN

2021-07-26T14:35:41Z

Link: /* Step 4: migrate WhatsApp proper to a VM */

'''WhatsApp''' is a popular communication app for Android and iOS. It is owned by Facebook, which has a hostile attitude towards alternative clients and open source software, along with [https://stallman.org/facebook.html being notorious for its egregious privacy violations (and de-facto support of white supremacy and fascism)]. It stands to reason, then, that WhatsApp is not an app that any privacy-conscious individual should want to have installed on their mobile phone, which typically holds a vast quantity of personal data. However, the unfortunate truth is that it tends to be virtually impossible for many of us to stop using WhatsApp without permanently losing contact with several friends, family members, clients or colleagues. Thus, one may seek to find a middle ground: keeping WhatsApp well away from one's personal devices, but somehow still connecting to its network using these devices. Given Facebook's hostile attitude to third-party clients, one might expect such a task to be impossible... or is it?

'''Enter the Matrix.''' [https://matrix.org/ Matrix] is a free (as in speech), feature-rich decentralised communication ecosystem that can serve as a platform for instant messaging, e.g. using [https://www.element.io/ Element] as a client. Although I would highly encourage switching from WhatsApp to Element whenever possible, it turns out Matrix is in fact capable of communicating with the WhatsApp network. This is done using [https://github.com/tulir/mautrix-whatsapp mautrix-whatsapp], which masquerades as a WhatsApp Web client and uses it to communicate with the actual WhatsApp client running on a phone or emulator.

'''A note:''' this guide is essentially an amalgamation of the most relevant bits of various other guides: [https://wiki.debian.org/OpenVPN the Debian OpenVPN guide], [https://openvpn.net/community-resources/how-to/#installing-openvpn the OpenVPN community installation guide], [https://www.natrius.eu/dokuwiki/doku.php?id=digital:server:matrixsynapse the Synapse installation guide by '''natrius'''], the [https://gist.github.com/marcopaganini/0823d31d43557f9711e21b43a3223fce Nginx/TLS reverse proxy guide by '''Marco Paganini'''], [http://blog.hoxnox.com/inet/ssl_nginx.md.html the Nginx/easy-rsa guide by '''hoxnox'''], and the [https://github.com/tulir/mautrix-whatsapp/wiki/Bridge-setup official mautrix-whatsapp bridge setup guide by '''Tulir Asokan''']. These individual guides explain their steps in greater depth than I do here, and I highly, highly recommend reading through all of them before tackling a project like this one. '''Also be very aware that I am not an expert in any of this. If you need enterprise-grade security, close this browser tab now and consult an actual expert.''' That said, I have made an honest attempt to hammer down any security holes I could think of, and I am presently running this set-up myself.

=The set-up=
[[File:Mautrix-whatsapp-setup-pathified.svg]]

This guide will explain one possible configuration to use WhatsApp from a Matrix client. In this configuration, a Matrix homeserver (Synapse) and mautrix-whatsapp will be installed on a (virtual) private server, along with OpenVPN. The setup is completely contained within the virtual private network (VPN) created by OpenVPN, and does not require any entrypoints from the outside world except through the VPN (although you may want to enable SSH access for setup and administration). It therefore has a high degree of inherent security. A reverse HTTPS proxy is set up using Nginx with certificates generated by easy-rsa: this is necessary for some clients to be able to connect.

<code>iptables</code> is used for setting up routing and firewalling of the server, and only IPv4 is considered for the time being. I wish to ''eventually'' migrate to <code>nftables</code> and a dual IPv4/IPv6 stack, however this will take more time and effort than I have available, especially considering the current setup "just works" for me.

This guide is primarily focussed on a "single owner, multiple devices" configuration: extra security precautions should be taken if one wants to allow multiple individuals in the VPN, and using multiple WhatsApp accounts in particular is beyond the scope of this guide.

N.B. it is up to you to decide where WhatsApp (the actual proprietary app) goes in the graphic above: as shown, it is put on the VPS (in an emulator or VM), but it is also possible to leave it off the VPS, e.g. running on a normal phone. Off the VPS, you additionally have the choice of whether you want to route its traffic through the VPN (recommended) or not.

==Requirements==
* A WhatsApp account, and the WhatsApp app running either on a phone or in an emulator on a device with a webcam
* A (virtual) private server ((V)PS) with the following specs:
** A static IPv4 address
** Linux, ideally Debian 10
** root/<code>sudo</code> access
** At least 1 GB RAM
** At least 5 GB disk space for the software and text message storage
** More disk space for the media (videos, etc.) you send and receive
* Decent knowledge of Linux administration
* A free weekend or so to set up, test and tweak everything

The environment used in this guide is a VPS running Debian 10 with full root access; all commands are run as root unless otherwise stated. It is assumed that the VPS is in a fresh-off-the-shelf state with little more than <code>sshd</code> installed and running.

=Step 0: iptables and OpenVPN=
The first and foremost things to get working are the firewall and VPN server. ''Henceforth, we shall use '''192.168.16.0/24''' as the OpenVPN address space, and '''port 1194''' (UDP or TCP) as the OpenVPN port. Take extra care if you want to use something else. We shall use '''123.123.123.123''' as the externally reachable IP of the server; always replace this by whatever the actual address is.''

Log in to your VPS and install iptables as follows:
<syntaxhighlight lang="bash">
apt install iptables iptables-persistent
</syntaxhighlight>

Let us begin by setting up some basic security:
<syntaxhighlight lang="bash" line>
iptables -A INPUT -i lo -j ACCEPT
iptables -A INPUT -s 127.0.0.1/32 -j ACCEPT
iptables -A INPUT -m state --state RELATED,ESTABLISHED -j ACCEPT
iptables -A INPUT -p icmp -m icmp --icmp-type 8 -j ACCEPT
iptables -A INPUT -p icmp -m icmp --icmp-type 11 -j ACCEPT
iptables -A INPUT -p icmp -m icmp --icmp-type 3 -j ACCEPT
iptables -A INPUT -p tcp -m tcp --dport 22 -j ACCEPT
iptables -A INPUT -j DROP
iptables-save >/etc/iptables/rules.v4
</syntaxhighlight>

This will drop all incoming connections apart from SSH and a few ICMP messages. The last line preserves your iptables rules when rebooting.

The next step is to install OpenVPN. The instructions provided here mostly follow [https://wiki.debian.org/OpenVPN Debian's OpenVPN guide]; see that page for more in-depth information. Start by installing the required packages:
<syntaxhighlight lang="bash">
apt install easy-rsa openvpn
</syntaxhighlight>
Next, we create a certificate authority directory in <code>/etc/openvpn</code> and edit the config:
<syntaxhighlight lang="bash" line>
make-cadir /etc/openvpn/easy-rsa
cd /etc/openvpn/easy-rsa
editor vars
</syntaxhighlight>

The <code>vars</code> file has sensible defaults, but you may want to make a few changes (see the inline documentation if you are unsure):
# uncomment the line with <code>set_var EASYRSA_DN "cn_only"</code>
# set the key size to 4096: <code>set_var EASYRSA_KEY_SIZE 4096</code>
# set the CA validity to something long, like 10 years: <code>set_var EASYRSA_CA_EXPIRE 3650</code>
# set the certificate validity to something similar: <code>set_var EASYRSA_CERT_EXPIRE 3650</code>

After writing the vars file, create the certificate authority, a server certificate and Diffie-Hellman parameters:
<syntaxhighlight lang="bash" line>
./easyrsa init-pki
./easyrsa build-ca
./easyrsa build-server-full server nopass
./easyrsa gen-dh
</syntaxhighlight>
The <code>build-ca</code> step will prompt you for a name and password. The name can be whatever you like, e.g. "My OpenVPN CA". Choose something strong but memorable as the password. Every further interaction with the certificate authority will require this password.

Now create a certificate for every client (desktop, laptop, tablet, mobile phone, refrigerator...) you want to have access to the VPN/your WhatsApp account. It's a good idea to use a file name that allows you to tell these certificates apart, e.g. <code>hostname.n</code>, where <code>hostname</code> is the hostname of the device and <code>n</code> is a number indicating this is the n'th certificate issued for that hostname:
<syntaxhighlight lang="bash" line>
./easyrsa build-client-full alpha.0 nopass
./easyrsa build-client-full bravo.0 nopass
# And so on...
</syntaxhighlight>

Finally, per the [https://openvpn.net/community-resources/how-to/#installing-openvpn OpenVPN community installation guide], generate a shared secret TLS key:
<syntaxhighlight lang="bash" line>
cd /etc/openvpn/easy-rsa/pki/private
openvpn --genkey --secret ta.key
</syntaxhighlight>

Now edit the OpenVPN configuration file:
<syntaxhighlight lang="bash" line>
cd /etc/openvpn
editor server.conf
</syntaxhighlight>

A viable example configuration file follows. See <code>openvpn(8)</code> if it is unclear what an option does. Be sure to save this file as /etc/openvpn/server.conf.
<syntaxhighlight lang="cfg" line>
mode server
# Enable TLS encryption.
tls-server
# Listen on port 1194 (the default).
port 1194
# Set the protocol here. UDP is the default, but it may give you trouble
# connecting on low-quality public Wi-Fi. You can use `proto tcp-server'
# here instead, but note that this causes extra overhead.
# Choose `proto tcp-server' if you want to redirect port 443 to OpenVPN
# to allow connecting over some poorly configured public WiFi networks.
proto udp

# Use TUN device, as opposed to TAP. In 99% of cases, TUN is what you want.
# TAP configuration is outside the scope of this article.
dev tun
# IP pool to be used for OpenVPN. The parameters as given will put the server
# at 192.168.16.1 and clients at addresses up to 192.168.16.255.
server 192.168.16.0 255.255.255.0

# ca.crt file of the certificate authority we just set up.
ca /etc/openvpn/easy-rsa/pki/ca.crt
# Server certificate.
cert /etc/openvpn/easy-rsa/pki/issued/server.crt
# Server private key.
key /etc/openvpn/easy-rsa/pki/private/server.key
# Diffie-Hellman parameters.
dh /etc/openvpn/easy-rsa/pki/dh.pem
# TLS key.
tls-auth /etc/openvpn/easy-rsa/pki/private/ta.key 0

# Timeout parameters for sending pings/restarting OpenVPN. See openvpn(8).
keepalive 20 120
# Enable the following if you want clients to be able to address
# one another directly.
#client-to-client

# Compress the stream with LZO to limit bandwidth.
comp-lzo
# Allow at most 10 clients to connect at the same time.
# Increase if necessary, but make sure your network and server can handle
# the load.
max-clients 10

# Drop root privileges.
user nobody
group nogroup

# Persist keys and TUN device across restarts, since we are dropping root.
persist-key
persist-tun

# Status file.
status /var/log/openvpn-status.log
</syntaxhighlight>

Next, configure the firewall to allow OpenVPN clients. The first step depends on the protocol you chose set in the OpenVPN server configuration. If you chose UDP:
<syntaxhighlight lang="bash">
iptables -I INPUT 1 -p udp -m udp --dport 1194 -j ACCEPT
</syntaxhighlight>
OR, if you chose TCP:
<syntaxhighlight lang="bash">
iptables -I INPUT 1 -p tcp -m tcp --dport 1194 -j ACCEPT
</syntaxhighlight>

Next, set up forwarding and masquerading, and start the server! N.B. it is assumed here that the ethernet device of your server is eth0, and that OpenVPN creates the device <code>tun0</code> (i.e. nothing else sets up a TUN device before OpenVPN). Change tun0 and/or eth0 as necessary if this is not true.
<syntaxhighlight lang="bash" line>
iptables -A FORWARD -i tun0 -j ACCEPT
iptables -A FORWARD -i tun0 -o eth0 -m state --state RELATED,ESTABLISHED -j ACCEPT
iptables -A FORWARD -i eth0 -o tun0 -m state --state RELATED,ESTABLISHED -j ACCEPT
iptables -A POSTROUTING -s 192.168.16.0/24 -o eth0 -j MASQUERADE
iptables-save >/etc/iptables/rules.v4
echo "net.ipv4.ip_forward = 1" >>/etc/sysctl.conf
sysctl -p
systemctl enable openvpn.service
systemctl restart openvpn.service
ifconfig
ss -plunt
</syntaxhighlight>

Make sure OpenVPN starts correctly: <code>ifconfig</code> should show <code>tun0</code>, along with something like <code>inet 192.168.16.1 netmask 255.255.255.255 destination 192.168.16.2</code>. <code>ss -plunt</code> should show <code>0.0.0.0:1194</code> somewhere in the column labelled "Local Address:Port". If this is not the case, check <code>/var/log/daemon.log</code> for entries containing <code>ovpn-server</code>.

You must now copy some certificate files to your clients. As an example, if you have a Linux client named "alpha" and can access your server as root via SSH on 123.123.123.123, run the following commands as root on "alpha" (assuming OpenVPN is already installed):
<syntaxhighlight lang="bash" line>
cd /etc/openvpn
scp 123.123.123.123:/etc/openvpn/easy-rsa/pki/'{ca.crt,issued/alpha.0.crt,private/alpha.0.key,private/ta.key}' .
</syntaxhighlight>

An example of a client configuration file (save as <code>/etc/openvpn/client.conf</code>) is listed below.
<syntaxhighlight lang="cfg" line>
client
dev tun
# Use `proto udp' if that's what the server uses.
# Else use `proto tcp-client'.
proto udp
remote 123.123.123.123 1194
resolv-retry infinite
nobind

user nobody
group nobody
persist-key
persist-tun

ca /etc/openvpn/ca.crt
cert /etc/openvpn/alpha.0.crt
key /etc/openvpn/alpha.0.key

ns-cert-type server

tls-auth /etc/openvpn/ta.key 1

comp-lzo

# Uncomment the following if you want to redirect all client traffic through
# the VPN. (Without it, only 192.168.16.0/24 will be routed through the VPN.)
#redirect-gateway def1
</syntaxhighlight>

On "alpha", run <code>openvpn --config /etc/openvpn/client.conf</code> and check if it will connect. Running <code>ifconfig</code> on "alpha" should show a <code>tun0</code> with an IP in 129.168.16.0/24 and a destination of 192.168.16.1. You should be able to SSH over the VPN too, using
<syntaxhighlight lang="bash">
ssh root@192.168.16.1
</syntaxhighlight>

If this connects, your VPN works and you're done with this step!

=Step 1: PostgreSQL and Synapse=
Synapse is the name of the Matrix homeserver reference implementation, which we will be installing in this section. This procedure loosely follows [https://www.natrius.eu/dokuwiki/doku.php?id=digital:server:matrixsynapse the guide by '''natrius'''], with some key differences:
# We will thoroughly disable federation.
# We will use easy-rsa to add self-signed certificates to the Nginx reverse proxy.
# We will use <code>iptables</code> instead of <code>ufw</code>.

Before installing Synapse, first install PostgreSQL and its Python binding:
<syntaxhighlight lang="bash">
apt install postgresql python3-psycopg2
</syntaxhighlight>

Now <code>su</code> to the PostgreSQL admin account and start the PostgreSQL shell:
<syntaxhighlight lang="bash" line>
su - postgres
psql
</syntaxhighlight>

As in natrius' guide, create the synapse database and a user to own it:
<syntaxhighlight lang="sql" line>
CREATE USER "synapse" WITH PASSWORD 'password';
CREATE DATABASE synapse ENCODING 'UTF8' LC_COLLATE='C' LC_CTYPE='C' template=template0 OWNER "synapse";
\q
</syntaxhighlight>
Replace 'password' with a strong, ideally random password. That's all that's needed as far as PostgreSQL goes, so log out of the <code>postgres</code> account.

As in the aforementioned guide, first add the relevant repositories and perform any necessary updates, and then install Synapse:
<syntaxhighlight lang="bash" line>
apt install lsb-release wget apt-transport-https
wget -O /usr/share/keyrings/matrix-org-archive-keyring.gpg https://packages.matrix.org/debian/matrix-org-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/matrix-org-archive-keyring.gpg] https://packages.matrix.org/debian/ $(lsb_release -cs) main" | tee /etc/apt/sources.list.d/matrix-org.list
apt update && apt upgrade
apt install matrix-synapse-py3
</syntaxhighlight>

When asked for a hostname, enter <code>localhost</code>. Next, edit the configuration file, <code>/etc/matrix-synapse/homeserver.yaml</code>. In the <code>listeners</code> section, change the uncommented lines to the following:
<syntaxhighlight lang="yaml" line>
- port: 8008
tls: false
type: http
x_forwarded: true
bind_addresses: ['0.0.0.0']

resources:
- names: [client]
compress: false
</syntaxhighlight>
That is, we bind 0.0.0.0 (to listen to the whole network for client connections) and remove federation.

We will be even more thorough in disabling federation: search for <code>federation_domain_whitelist</code>, which (for the Debian 10 configuration file of Synapse 1.23) should be a commented line with a few domains under it. Add a new line after that comment section:
<syntaxhighlight lang="yaml">
federation_domain_whitelist: []
</syntaxhighlight>

Next scroll down to <code>federation_ip_range_blacklist</code> and remove the IPs underneath that line. Replace them with the IPv4 and IPv6 catchalls:
<syntaxhighlight lang="yaml" line>
- '0.0.0.0/0'
- '::/0'
</syntaxhighlight>

With federation now thoroughly disabled, look for <code>enable_registration: false</code> and uncomment this line. As in natrius' guide, look for <code>registration_shared_secret: <PRIVATE STRING></code>, uncomment it, and replace <code><PRIVATE STRING></code> with a long, randomly generated alphanumeric string, e.g. generated by the command
<syntaxhighlight lang="bash">
cat /dev/urandom | tr -dc 'a-zA-Z0-9' | fold -w 32 | head -n 1
</syntaxhighlight>

Write out the configuration file and exit your editor. We now need to open port 8008 to VPN clients:
<syntaxhighlight lang="bash" line>
iptables -I INPUT 1 -s 192.168.16.0/24 -i tun0 -p tcp -m tcp --dport 8008 -j ACCEPT
iptables-save >/etc/iptables/rules.v4
</syntaxhighlight>

Now start Synapse and check if it is running:
<syntaxhighlight lang="bash" line>
systemctl start matrix-synapse.service
ss -plunt
</syntaxhighlight>

The last command should show that Synapse is listening on port 8008.

You can now create an account on your homeserver:
<syntaxhighlight lang="bash">
register_new_matrix_user -c /etc/matrix-synapse/homeserver.yaml http://localhost:8008
</syntaxhighlight>
This will prompt for a username and password, as well as the shared secret you entered into the configuration file earlier.

If you have a PC or laptop that you've given access to the VPN, you can install the '''desktop''' [https://element.io/get-started Element] client on it. You should then be able to connect to <code>http://192.168.16.1:8008</code> using the account you just created. At this moment, the Android and Web clients do NOT support HTTP connections, so these clients cannot connect to your Synapse installation yet. Which brings us to...

=Step 2: Nginx and TLS=
To allow most clients to connect to your homeserver (provided they have access to the VPN), you will need to set up a reverse proxy that adds a TLS layer so they can communicate over HTTPS. While the Synapse guide by natrius recommends Let's Encrypt certificates, in a fully private context like we are considering, it makes sense to set up your own certificate authority.

I opted to build a new certificate authority in the Synapse configuration directory and reuse the configuration I picked for OpenVPN:
<syntaxhighlight lang="bash" line>
make-cadir /etc/matrix-synapse/easy-rsa
cd /etc/matrix-synapse/easy-rsa
cp /etc/openvpn/easy-rsa/vars .
./easyrsa init-pki
./easyrsa --subject-alt-name="IP:192.168.16.1" build-ca
# Choose a new CA name when prompted. The password you are prompted for
# should ideally also be different from the one you used for OpenVPN.
./easyrsa --subject-alt-name="IP:192.168.16.1" build-server-full matrix-synapse nopass
# For all clients:
./easyrsa --subject-alt-name="IP:192.168.16.1" build-client-full alpha.0 nopass
./easyrsa --subject-alt-name="IP:192.168.16.1" build-client-full bravo.0 nopass
# ...and so on
</syntaxhighlight>

Note that we are now including <code>--subject-alt-name="IP:192.168.16.1"</code> in our commands. HTTPS requires certificates to be bound to a domain or IP, and browsers tend to get ornery if they are not. We do not need Diffie-Hellman parameters now, but we do need to generate a certificate revocation list so Nginx will be able to reject revoked certificates, and we must also export our client certificates in a format browsers and mobile OSes understand:
<syntaxhighlight lang="bash" list>
# For all clients:
./easyrsa export-p12 alpha.0
./easyrsa export-p12 bravo.0
# ...and so on
./easyrsa gen-crl
</syntaxhighlight>
The export step asks you to provide a password, which allows you to securely transport the exported certificates to the clients they are to be installed on.

Next up, Nginx. Install the package, remove the default configuration, and create a new one:
<syntaxhighlight lang="bash" line>
apt install nginx
systemctl stop nginx.service
unlink /etc/nginx/sites-enabled/default
ln -s /etc/nginx/sites-available/synapse /etc/nginx/sites-enabled/synapse
editor /etc/nginx/sites-available/synapse
</syntaxhighlight>

An example configuration that sets up an HTTPS reverse proxy on port 10443 is
given below.
<syntaxhighlight lang="nginx" line>
server {
listen 10443 ssl;
server_name localhost;

ssl on;
ssl_certificate /etc/matrix-synapse/easy-rsa/pki/issued/matrix-synapse.crt;
ssl_certificate_key /etc/matrix-synapse/easy-rsa/pki/private/matrix-synapse.key;
ssl_client_certificate /etc/matrix-synapse/easy-rsa/pki/ca.crt;
ssl_crl /etc/matrix-synapse/easy-rsa/pki/crl.pem;
# Enable mutual TLS. This option provides maximal security by requiring
# per-client certificates. Unfortunately, client-side support for this
# tends to be shaky at best, so turn it off and restart Nginx if you are
# not able to connect.
ssl_verify_client on;

access_log /var/log/nginx-synapse-access_log.log;
error_log /var/log/nginx-synapse-error_log.log;

# There is no need to serve files, and we will not be using
# .well-known, since we don't use federation. So we just reverse-proxy
# Synapse's HTTP at the root and that's it.
location / {
proxy_pass http://127.0.0.1:8008;
proxy_set_header X-Forwarded-For $remote_addr;
}
}
</syntaxhighlight>

Now unblock port 10443 for the VPN and start Nginx:
<syntaxhighlight lang="bash" line>
iptables -I INPUT 1 -s 192.168.16.0/24 -i tun0 -p tcp -m tcp --dport 10443 -j ACCEPT
iptables-save >/etc/iptables/rules.v4
systemctl enable nginx.service
systemctl start nginx.service
# Check if it's running
ss -plunt
</syntaxhighlight>

The last command should show Nginx listening on port 10443. Now copy <code>/etc/matrix-synapse/easy-rsa/pki/ca.crt</code> to all clients and import it as a trusted system certificate. Also copy each <code>p12</code> certificate in <code>/etc/matrix-synapse/easy-rsa/pki/private/</code> to its respective client and import it.

The desktop and android apps should now be able to at least communicate with the server via HTTPS at <code>https://192.168.16.1:10443</code>. If, however, you get an error stating the client did not send the correct certificate, you may have to disable <code>ssl_verify_client</code> in the Nginx configuration file and restart Nginx. Note that the canonical Element-web implementation at app.element.io may not be able to talk to your server regardless; I believe this is because browsers will restrict accessing local networks from sites loaded from remote servers. Installing element-web locally will help; see Optional Extras at the end of this guide.

=Step 3: mautrix-whatsapp=
Being a rather niche package, mautrix-whatsapp is not in the Debian repositories and must be self-compiled. It also has some dependencies on versions of packages too recent to be found in the repositories of Debian 10 (buster)

First and foremost, version 1.14 of Go (<code>golang-1.14</code>) is needed at the time of writing, which has been backported to buster. If you are running buster, install Go as follows:
<syntaxhighlight lang="bash" line>
echo 'deb http://deb.debian.org/debian buster-backports main' >>/etc/apt/sources.list
apt update
apt install -t buster-backports golang
</syntaxhighlight>

Alternatively, if you are using Debian 11 (bullseye) or Unstable (sid), simply install golang directly:
<syntaxhighlight lang="bash">
apt install golang
</syntaxhighlight>

Regardless of your Debian version, you will need to install <code>ffmpeg</code>, a GNU toolchain, and <code>git</code>, if they are not already installed:
<syntaxhighlight lang="bash">
apt install ffmpeg make autoconf automake libtool gcc cmake git
</syntaxhighlight>

Next, we need to install a very recent version of <code>olm</code>, which must be hand-compiled at the time of writing. It is probably best to perform the following steps as a regular user instead of root, but I couldn't be bothered creating a new user. Caveat emptor.
<syntaxhighlight lang="bash">
cd
git clone https://gitlab.matrix.org/matrix-org/olm.git
cd olm
cmake . -Bbuild
cd build
make
# if you dropped root, use `sudo make install' here instead
make install
</syntaxhighlight>

We are now ready to compile mautrix-whatsapp. The following steps may also be executed as a regular user if you want. Clone the repo and compile:
<syntaxhighlight lang="bash" line>
cd
git clone https://github.com/tulir/mautrix-whatsapp.git
cd mautrix-whatsapp
export LD_LIBRARY_PATH=/usr/local/lib
./build.sh
# Only execute the following if you executed the above as a regular user
cd ..
sudo cp -r mautrix-whatsapp /root/mautrix-whatsapp
</syntaxhighlight>

Again as root, copy <code>/root/mautrix-whatsapp/example-config.yaml</code> to <code>/root/mautrix-whatsapp/config.yaml</code> and edit the latter.
* Under <code>homeserver</code>, set <code>address</code> to <code>http://localhost:8008</code> and <code>domain</code> to <code>localhost</code>.
* Under <code>appservice</code>, set <code>hostname</code> to <code>127.0.0.1</code>.
* Under <code>database</code> (in the <code>appservice</code> section), set <code>type</code> to <code>postgres</code> and <code>uri</code> to <code>postgres://synapse:<password>@localhost/synapse?sslmode=disable</code>, where <code><password></code> should be replaced with the PostgreSQL password you picked earlier.
* Under <code>bridge</code>, set <code>private_chat_portal_meta</code> to <code>true</code>.

The <code>permissions</code> block under <code>bridge</code> should be something like this:
<syntaxhighlight lang="yaml" line>
permissions:
"*": relaybot
"localhost": user
"@alice:localhost": admin
</syntaxhighlight>
Here <code>alice</code> should be replaced with the username you chose when issuing the <code>register_new_matrix_user</code> command in Step 1.

Finally, set <code>directory</code> under <code>logging</code> to something more suitable, like <code>/var/log/mautrix-whatsapp</code>.

Now generate the appservice registration file, copy it to the Synapse configuration directory, and change its ownership so Synapse can read it:
<syntaxhighlight lang="bash" line>
cd /root/mautrix-whatsapp
export LD_LIBRARY_PATH=/usr/local/lib
./mautrix-whatsapp -g
cp registration.yaml /etc/matrix-synapse/wa_registration.yaml
chown matrix-synapse /etc/matrix-synapse/wa_registration.yaml
</syntaxhighlight>

Edit <code>/etc/matrix-synapse/homeserver.yaml</code>. Find the line with <code>app_service_config_files</code> (which is commented out) and, below the comment, add
<syntaxhighlight lang="yaml" line>
app_service_config_files:
- "/etc/matrix-synapse/wa_registration.yaml"
</syntaxhighlight>

Now restart Synapse:
<syntaxhighlight lang="bash">
systemctl restart matrix-synapse.service
</syntaxhighlight>

It is now time to test mautrix-whatsapp. For testing purposes, start the bridge in the foreground:
<syntaxhighlight lang="bash">
/root/mautrix-whatsapp/mautrix-whatsapp
</syntaxhighlight>

Connect to your homeserver with Element-Desktop or Element-Android and start a direct chat with <code>@whatsappbot:localhost</code>. You should get a message saying the room has been set up as the bridge management/status room. Type <code>help</code> and send the message. If the bot replies, you're good; if not, check the logs, and check/adjust your configuration carefully and restart Synapse and mautrix-whatsapp.

If all is working, go back to the terminal where you started <code>/root/mautrix-whatsapp/mautrix-whatsapp</code> and terminate the process with Ctrl-C. Now create a new file <code>/etc/systemd/system/mautrix-whatsapp.service</code> and enter the following:
<syntaxhighlight lang="ini" line>
[Unit]
Description=WhatsApp to Matrix bridge
Wants=matrix-synapse.service

[Service]
Type=exec
Environment="LD_LIBRARY_PATH=/usr/local/lib"
WorkingDirectory=/root/mautrix-whatsapp
ExecStart=/root/mautrix-whatsapp/mautrix-whatsapp
Restart=always
RestartSec=10
SyslogIdentifier=mautrix-whatsapp

[Install]
WantedBy=multi-user.target
</syntaxhighlight>

You should now be able to start mautrix-whatsapp using systemd:
<syntaxhighlight lang="bash" line>
systemctl start mautrix-whatsapp.service
systemctl enable mautrix-whatsapp.service
</syntaxhighlight>

Wait a few seconds for mautrix-whatsapp to finish loading, then message <code>help</code> to your bot again to make sure it still works. If it does, send it <code>login</code>, and use the actual (official) WhatsApp client to scan the WhatsApp Web QR code that the bot sends you. It should immediately start pulling a few chats, but most likely not your entire history. Ignore it for now. Open your Element client's settings, go to Help & Advanced, and find your access token. Copy it. Then send the bridge bot <code>login-matrix <access_token></code>, replacing <code><access_token></code> with the access token you just copied. This will enable double puppeting; see [https://github.com/tulir/mautrix-whatsapp/wiki/Authentication the Authentication guide].

If you are not content with the meagre amount of chats/messages pulled by the bot, go into each room it created and send <code>!wa delete-portal</code>. Then go back to your terminal/SSH session and edit <code>/root/mautrix-whatsapp/config.yaml</code> again. In the <code>bridge</code> section, edit these settings:
* <code>initial_chat_sync_count</code> -- this is the amount of WhatsApp group portals that should be created. You probably want to set this to at least the number of WhatsApp groups you're in, including "one-on-one" groups for people you've direct-messaged. If unsure, just pick a number that's definitely larger than that.
* <code>initial_history_fill_count</code> -- this is the amount of old messages that will be fetched. If you have some very active or old rooms, you will need a very large number here. One caveat: mautrix-whatsapp can get a bit wonky if it's syncing a large amount of messages, and may need to be killed and restarted a few times for the process to complete. That means you should also be monitoring the sync process.
* <code>sync_max_chat_age</code> -- this is the age cutoff in seconds for synced messages. Set it to something like 2000000000 (two billion seconds, or roughly 63 years) to effectively disable the age cutoff.
* <code>initial_history_disable_notifications</code> -- this determines whether you get a "new message" notification for every synced old message. If you set <code>initial_history_fill_count</code> to a large number, do yourself a ''huge'' favour and set this to <code>true</code>.

Now restart mautrix-whatsapp:
<syntaxhighlight lang="bash">
systemctl restart mautrix-whatsapp.service
</syntaxhighlight>

Finally, send the bridge bot <code>sync --create-all</code>. It will now start to pull the chats you chose. Bear in mind that this can take a very long time. If you notice it stops making progress, restart mautrix-whatsapp and send <code>sync --create-all</code> again: it will continue at the point it was stopped.

You are now basically done, although you probably still have WhatsApp running on your phone. The next step will explain how to migrate it to a VM.

=Step 4: migrate WhatsApp proper to a VM=
To be added. [https://github.com/tulir/mautrix-whatsapp/wiki/Android-VM-Setup The official guide by '''Alistair Francis'''] should get you quite far.

Caveat: if you do not have access to KVM on your server, you will need to use an ARM AVD in softemu mode. In my experience, Android versions higher than 4.1.x are too slow to be usable. However, 4.1.2 on an emulated Nexus One API 16 (WVGA) in softemu mode can run WhatsApp on a very modest VPS (albeit slowly).

=Step 5: optional extras=
Finally, there are a few things you can do to extend this setup.

==Redirect port 443 to OpenVPN==
Some public Wi-Fi networks only allow access to a very restricted set of ports so clients are limited to web-browsing and checking email. This annoying bit of shit-tier network administration is easily circumvented by piping your traffic through a VPN, which, of course, you just set up -- but you have to be able to connect to the VPN in the first place, and port 1194 (OpenVPN's default port) is practically guaranteed to be blocked by such networks. Luckily, the default HTTPS port, TCP 443, is practically guaranteed to NOT be blocked, so if your OpenVPN server is using TCP, you can just redirect traffic from 443 to 1194 and log in to your VPN on basically any network. ''N.B. switch your OpenVPN over to TCP if you want to do this but chose UDP earlier.''

A few commands are all that's needed:
<syntaxhighlight lang="bash" line>
iptables -A PREROUTING -i eth0 -p tcp -m tcp --dport 443 -j REDIRECT --to-ports 1194
iptables -I INPUT 1 -p tcp -m tcp --dport 443 -j ACCEPT
iptables-save >/etc/iptables/rules.v4
</syntaxhighlight>

You can now use <code>remote 123.123.123.123 443</code> in your client configuration files. Also be sure to add <code>redirect-gateway def1</code> on clients that connect to public Wi-Fi!

==Install element-web==
The official element-web implementation at app.element.io does not work with a private homeserver, but element-web ''will'' work if you install it on your homeserver. '''Note that the authors of element-web specifically recommend against running element-web on the same domain as the homeserver.''' However, as access is limited to the VPN, the risk should be limited as long as only trusted and experienced users are allowed access to the VPN in the first place.

Download the latest release (1.75-rc1 at the time of writing; replace the version as necessary in what follows, obviously) from [https://github.com/vector-im/element-web/releases], extract it, move it to the proper place, and create the config file:
<syntaxhighlight lang="bash" line>
wget https://github.com/vector-im/element-web/releases/download/v1.7.15-rc.1/element-v1.7.15-rc.1.tar.gz
tar -xvzf element-v1.7.15-rc.1.tar.gz
mv element-v1.7.15-rc.1 /var/www/element-web
cd /var/www/element-web
cp config.sample.json config.json
</syntaxhighlight>

Edit <code>config.json</code>. Set <code>"base_url"</code> to <code>"https://192.168.16.1:10443"</code> and <code>"server_name"</code> to <code>"localhost"</code> in the <code>"m.homeserver"</code> block near the top. In the root block, set <code>"disable_custom_urls"</code> to <code>true</code> and <code>"default_federate"</code> to <code>false</code>.

Since we've already set up Nginx, we can just tell it to serve element-web as well, and we can even reuse the certificate authority. Edit the configuration file you created earlier, <code>/etc/nginx/sites-available/synapse</code> and add the following block at the end:
<syntaxhighlight lang="nginx" line>
server {
listen 10444 ssl;
server_name localhost;

root /var/www/element-web;
index index.html;

ssl on;
ssl_certificate /etc/matrix-synapse/easy-rsa/pki/issued/element-web.crt;
ssl_certificate_key /etc/matrix-synapse/easy-rsa/pki/private/element-web.key;
ssl_client_certificate /etc/matrix-synapse/easy-rsa/pki/ca.crt;
ssl_crl /etc/matrix-synapse/easy-rsa/pki/crl.pem;
ssl_verify_client on;

access_log /var/log/nginx-element-web-access_log.log;
error_log /var/log/nginx-element-web-error_log.log;
}
</syntaxhighlight>

If you did not manage to get <code>ssl_verify_client</code> to work earlier, remove that line here too. Also, if you did not use port 443 for OpenVPN, you may use <code>listen 443 ssl;</code> instead of <code>listen 10444 ssl;</code> if you want (so you can just point your browser at https://192.168.16.1). Finally, add an iptables rule to allow connecting from within the VPN, and restart Nginx:
<syntaxhighlight lang="bash" line>
# Replace 10444 with 443 if necessary
iptables -I INPUT 1 -s 192.168.16.0/24 -i tun0 -p tcp -m tcp --dport 10444 -j ACCEPT
iptables-save >/etc/iptables/rules.v4
systemctl restart nginx.service
</syntaxhighlight>

==Block Facebook on clients==
On all clients (except the phone running WhatsApp, if you have not moved it to a VM on the server yet), you can now completely block all Facebook-owned IPs and still retain access to WhatsApp using your Matrix homeserver. While tedious to do by hand (considering Facebook's IP pool grows like an aggressive tumour), it is easily automated on Linux with a cron job and iptables.

First of all, create a new iptables chain that will be used for automated IP blocking, and add it to the front of your INPUT and OUTPUT chains:
<syntaxhighlight lang="bash" line>
iptables -N BLOCK
iptables -I INPUT 1 -j BLOCK
iptables -I OUTPUT 1 -j BLOCK
</syntaxhighlight>

Next, we will create a script that finds the list of IPs owned by Facebook and adds them to the BLOCK chain. N.B. this requires <code>whois</code>, which should be available in any package manager under that name, so install it first if necessary. Then create the file <code>/etc/cron.hourly/ipblock.sh</code> with the following contents:
<syntaxhighlight lang="bash" line>
#!/bin/bash
iptables=/sbin/iptables

$iptables -F BLOCK

asns="AS32934"
for asn in asns
do
ips="$(whois -h whois.radb.net -- -i origin -T route $asn | grep route: | awk '{print $2}')"
for i in $ips
do
$iptables -A BLOCK -d $i -j REJECT --reject-with icmp-host-unreachable
$iptables -A BLOCK -s $i -j REJECT --reject-with icmp-host-unreachable
done
done
</syntaxhighlight>

This script queries whois.radb.net to find all IPs registered under the [https://en.wikipedia.org/wiki/Autonomous_system_(Internet) autonomous system number] AS32934, which is Facebook. You may add other ASNs too if you want. Note that although the list "only" contains 200 entries or so (at the time of writing), they include mask bits in CIDR notation: this list in fact represents tens of thousands of IP addresses, all owned by Facebook.

Make sure to make the script executable, and run it once if you don't want to wait until the next hour for cron to do it.
<syntaxhighlight lang="bash" line>
chmod +x /etc/cron.hourly/ipblock.sh
/etc/cron.hourly/ipblock.sh
iptables-save >/etc/iptables/rules.v4
</syntaxhighlight>

==Honourable mention: Pi-hole==
This is an honourable mention because I will not describe the installation process here and it is not related to mautrix-whatsapp. Nevertheless, as following this guide leaves you with a perfectly usable VPN server, and people reading this are likely to be privacy-conscious, I feel it is worthwhile to link [https://pi-hole.net/ Pi-hole] here. Pi-hole is a very powerful ad-blocking framework acting at DNS level. Like Synapse, you can configure Pi-hole to only be accessible to clients inside your VPN (by allowing only connections from 192.168.16.0/24 on device tun0). On your VPN clients, you can set 192.168.16.1 as your primary DNS server, so all clients are protected from malicious ads when connected to the VPN.

==Honourable mention: Tor proxy==
Your VPS can also serve as a VPN-wide proxy that sends traffic through [https://www.torproject.org/ Tor]. [https://www.marcus-povey.co.uk/2016/03/24/using-tor-as-a-http-proxy/ '''Marcus Povey''' has created a guide on how to set up a Tor proxy with polipo.]

Considering Tor's abysmal transfer speed, you probably don't ''always'' want to redirect traffic over Tor. Most browsers support [https://en.wikipedia.org/wiki/Proxy_auto-config proxy auto-config] (PAC), which allows you to fine-tune which sites get piped through the proxy. For example, the following PAC uses the Tor proxy to handle [https://en.wikipedia.org/wiki/.onion .onion] domains:
<syntaxhighlight lang="javascript" line>
function FindProxyForURL (url, host)
{
if (shExpMatch (host, "*.onion"))
{
return "PROXY 192.168.16.1:8123"
}
return "DIRECT;"
}
</syntaxhighlight>

Much more advanced configurations are possible with proxy auto-config, e.g. redirecting all HTTP traffic but not HTTPS, whitelisting/blacklisting domains.

Matrix Synapse and mautrix-whatsapp in a VPN

2020-12-12T13:35:19Z

Link: Remove global LD_LIBRARY_PATH.

'''WhatsApp''' is a popular communication app for Android and iOS. It is owned by Facebook, which has a hostile attitude towards alternative clients and open source software, along with [https://stallman.org/facebook.html being notorious for its egregious privacy violations (and de-facto support of white supremacy and fascism)]. It stands to reason, then, that WhatsApp is not an app that any privacy-conscious individual should want to have installed on their mobile phone, which typically holds a vast quantity of personal data. However, the unfortunate truth is that it tends to be virtually impossible for many of us to stop using WhatsApp without permanently losing contact with several friends, family members, clients or colleagues. Thus, one may seek to find a middle ground: keeping WhatsApp well away from one's personal devices, but somehow still connecting to its network using these devices. Given Facebook's hostile attitude to third-party clients, one might expect such a task to be impossible... or is it?

'''Enter the Matrix.''' [https://matrix.org/ Matrix] is a free (as in speech), feature-rich decentralised communication ecosystem that can serve as a platform for instant messaging, e.g. using [https://www.element.io/ Element] as a client. Although I would highly encourage switching from WhatsApp to Element whenever possible, it turns out Matrix is in fact capable of communicating with the WhatsApp network. This is done using [https://github.com/tulir/mautrix-whatsapp mautrix-whatsapp], which masquerades as a WhatsApp Web client and uses it to communicate with the actual WhatsApp client running on a phone or emulator.

'''A note:''' this guide is essentially an amalgamation of the most relevant bits of various other guides: [https://wiki.debian.org/OpenVPN the Debian OpenVPN guide], [https://openvpn.net/community-resources/how-to/#installing-openvpn the OpenVPN community installation guide], [https://www.natrius.eu/dokuwiki/doku.php?id=digital:server:matrixsynapse the Synapse installation guide by '''natrius'''], the [https://gist.github.com/marcopaganini/0823d31d43557f9711e21b43a3223fce Nginx/TLS reverse proxy guide by '''Marco Paganini'''], [http://blog.hoxnox.com/inet/ssl_nginx.md.html the Nginx/easy-rsa guide by '''hoxnox'''], and the [https://github.com/tulir/mautrix-whatsapp/wiki/Bridge-setup official mautrix-whatsapp bridge setup guide by '''Tulir Asokan''']. These individual guides explain their steps in greater depth than I do here, and I highly, highly recommend reading through all of them before tackling a project like this one. '''Also be very aware that I am not an expert in any of this. If you need enterprise-grade security, close this browser tab now and consult an actual expert.''' That said, I have made an honest attempt to hammer down any security holes I could think of, and I am presently running this set-up myself.

=The set-up=
[[File:Mautrix-whatsapp-setup-pathified.svg]]

This guide will explain one possible configuration to use WhatsApp from a Matrix client. In this configuration, a Matrix homeserver (Synapse) and mautrix-whatsapp will be installed on a (virtual) private server, along with OpenVPN. The setup is completely contained within the virtual private network (VPN) created by OpenVPN, and does not require any entrypoints from the outside world except through the VPN (although you may want to enable SSH access for setup and administration). It therefore has a high degree of inherent security. A reverse HTTPS proxy is set up using Nginx with certificates generated by easy-rsa: this is necessary for some clients to be able to connect.

<code>iptables</code> is used for setting up routing and firewalling of the server, and only IPv4 is considered for the time being. I wish to ''eventually'' migrate to <code>nftables</code> and a dual IPv4/IPv6 stack, however this will take more time and effort than I have available, especially considering the current setup "just works" for me.

This guide is primarily focussed on a "single owner, multiple devices" configuration: extra security precautions should be taken if one wants to allow multiple individuals in the VPN, and using multiple WhatsApp accounts in particular is beyond the scope of this guide.

N.B. it is up to you to decide where WhatsApp (the actual proprietary app) goes in the graphic above: as shown, it is put on the VPS (in an emulator or VM), but it is also possible to leave it off the VPS, e.g. running on a normal phone. Off the VPS, you additionally have the choice of whether you want to route its traffic through the VPN (recommended) or not.

==Requirements==
* A WhatsApp account, and the WhatsApp app running either on a phone or in an emulator on a device with a webcam
* A (virtual) private server ((V)PS) with the following specs:
** A static IPv4 address
** Linux, ideally Debian 10
** root/<code>sudo</code> access
** At least 1 GB RAM
** At least 5 GB disk space for the software and text message storage
** More disk space for the media (videos, etc.) you send and receive
* Decent knowledge of Linux administration
* A free weekend or so to set up, test and tweak everything

The environment used in this guide is a VPS running Debian 10 with full root access; all commands are run as root unless otherwise stated. It is assumed that the VPS is in a fresh-off-the-shelf state with little more than <code>sshd</code> installed and running.

=Step 0: iptables and OpenVPN=
The first and foremost things to get working are the firewall and VPN server. ''Henceforth, we shall use '''192.168.16.0/24''' as the OpenVPN address space, and '''port 1194''' (UDP or TCP) as the OpenVPN port. Take extra care if you want to use something else. We shall use '''123.123.123.123''' as the externally reachable IP of the server; always replace this by whatever the actual address is.''

Log in to your VPS and install iptables as follows:
<syntaxhighlight lang="bash">
apt install iptables iptables-persistent
</syntaxhighlight>

Let us begin by setting up some basic security:
<syntaxhighlight lang="bash" line>
iptables -A INPUT -i lo -j ACCEPT
iptables -A INPUT -s 127.0.0.1/32 -j ACCEPT
iptables -A INPUT -m state --state RELATED,ESTABLISHED -j ACCEPT
iptables -A INPUT -p icmp -m icmp --icmp-type 8 -j ACCEPT
iptables -A INPUT -p icmp -m icmp --icmp-type 11 -j ACCEPT
iptables -A INPUT -p icmp -m icmp --icmp-type 3 -j ACCEPT
iptables -A INPUT -p tcp -m tcp --dport 22 -j ACCEPT
iptables -A INPUT -j DROP
iptables-save >/etc/iptables/rules.v4
</syntaxhighlight>

This will drop all incoming connections apart from SSH and a few ICMP messages. The last line preserves your iptables rules when rebooting.

The next step is to install OpenVPN. The instructions provided here mostly follow [https://wiki.debian.org/OpenVPN Debian's OpenVPN guide]; see that page for more in-depth information. Start by installing the required packages:
<syntaxhighlight lang="bash">
apt install easy-rsa openvpn
</syntaxhighlight>
Next, we create a certificate authority directory in <code>/etc/openvpn</code> and edit the config:
<syntaxhighlight lang="bash" line>
make-cadir /etc/openvpn/easy-rsa
cd /etc/openvpn/easy-rsa
editor vars
</syntaxhighlight>

The <code>vars</code> file has sensible defaults, but you may want to make a few changes (see the inline documentation if you are unsure):
# uncomment the line with <code>set_var EASYRSA_DN "cn_only"</code>
# set the key size to 4096: <code>set_var EASYRSA_KEY_SIZE 4096</code>
# set the CA validity to something long, like 10 years: <code>set_var EASYRSA_CA_EXPIRE 3650</code>
# set the certificate validity to something similar: <code>set_var EASYRSA_CERT_EXPIRE 3650</code>

After writing the vars file, create the certificate authority, a server certificate and Diffie-Hellman parameters:
<syntaxhighlight lang="bash" line>
./easyrsa init-pki
./easyrsa build-ca
./easyrsa build-server-full server nopass
./easyrsa gen-dh
</syntaxhighlight>
The <code>build-ca</code> step will prompt you for a name and password. The name can be whatever you like, e.g. "My OpenVPN CA". Choose something strong but memorable as the password. Every further interaction with the certificate authority will require this password.

Now create a certificate for every client (desktop, laptop, tablet, mobile phone, refrigerator...) you want to have access to the VPN/your WhatsApp account. It's a good idea to use a file name that allows you to tell these certificates apart, e.g. <code>hostname.n</code>, where <code>hostname</code> is the hostname of the device and <code>n</code> is a number indicating this is the n'th certificate issued for that hostname:
<syntaxhighlight lang="bash" line>
./easyrsa build-client-full alpha.0 nopass
./easyrsa build-client-full bravo.0 nopass
# And so on...
</syntaxhighlight>

Finally, per the [https://openvpn.net/community-resources/how-to/#installing-openvpn OpenVPN community installation guide], generate a shared secret TLS key:
<syntaxhighlight lang="bash" line>
cd /etc/openvpn/easy-rsa/pki/private
openvpn --genkey --secret ta.key
</syntaxhighlight>

Now edit the OpenVPN configuration file:
<syntaxhighlight lang="bash" line>
cd /etc/openvpn
editor server.conf
</syntaxhighlight>

A viable example configuration file follows. See <code>openvpn(8)</code> if it is unclear what an option does. Be sure to save this file as /etc/openvpn/server.conf.
<syntaxhighlight lang="cfg" line>
mode server
# Enable TLS encryption.
tls-server
# Listen on port 1194 (the default).
port 1194
# Set the protocol here. UDP is the default, but it may give you trouble
# connecting on low-quality public Wi-Fi. You can use `proto tcp-server'
# here instead, but note that this causes extra overhead.
# Choose `proto tcp-server' if you want to redirect port 443 to OpenVPN
# to allow connecting over some poorly configured public WiFi networks.
proto udp

# Use TUN device, as opposed to TAP. In 99% of cases, TUN is what you want.
# TAP configuration is outside the scope of this article.
dev tun
# IP pool to be used for OpenVPN. The parameters as given will put the server
# at 192.168.16.1 and clients at addresses up to 192.168.16.255.
server 192.168.16.0 255.255.255.0

# ca.crt file of the certificate authority we just set up.
ca /etc/openvpn/easy-rsa/pki/ca.crt
# Server certificate.
cert /etc/openvpn/easy-rsa/pki/issued/server.crt
# Server private key.
key /etc/openvpn/easy-rsa/pki/private/server.key
# Diffie-Hellman parameters.
dh /etc/openvpn/easy-rsa/pki/dh.pem
# TLS key.
tls-auth /etc/openvpn/easy-rsa/pki/private/ta.key 0

# Timeout parameters for sending pings/restarting OpenVPN. See openvpn(8).
keepalive 20 120
# Enable the following if you want clients to be able to address
# one another directly.
#client-to-client

# Compress the stream with LZO to limit bandwidth.
comp-lzo
# Allow at most 10 clients to connect at the same time.
# Increase if necessary, but make sure your network and server can handle
# the load.
max-clients 10

# Drop root privileges.
user nobody
group nogroup

# Persist keys and TUN device across restarts, since we are dropping root.
persist-key
persist-tun

# Status file.
status /var/log/openvpn-status.log
</syntaxhighlight>

Next, configure the firewall to allow OpenVPN clients. The first step depends on the protocol you chose set in the OpenVPN server configuration. If you chose UDP:
<syntaxhighlight lang="bash">
iptables -I INPUT 1 -p udp -m udp --dport 1194 -j ACCEPT
</syntaxhighlight>
OR, if you chose TCP:
<syntaxhighlight lang="bash">
iptables -I INPUT 1 -p tcp -m tcp --dport 1194 -j ACCEPT
</syntaxhighlight>

Next, set up forwarding and masquerading, and start the server! N.B. it is assumed here that the ethernet device of your server is eth0, and that OpenVPN creates the device <code>tun0</code> (i.e. nothing else sets up a TUN device before OpenVPN). Change tun0 and/or eth0 as necessary if this is not true.
<syntaxhighlight lang="bash" line>
iptables -A FORWARD -i tun0 -j ACCEPT
iptables -A FORWARD -i tun0 -o eth0 -m state --state RELATED,ESTABLISHED -j ACCEPT
iptables -A FORWARD -i eth0 -o tun0 -m state --state RELATED,ESTABLISHED -j ACCEPT
iptables -A POSTROUTING -s 192.168.16.0/24 -o eth0 -j MASQUERADE
iptables-save >/etc/iptables/rules.v4
echo "net.ipv4.ip_forward = 1" >>/etc/sysctl.conf
sysctl -p
systemctl enable openvpn.service
systemctl restart openvpn.service
ifconfig
ss -plunt
</syntaxhighlight>

Make sure OpenVPN starts correctly: <code>ifconfig</code> should show <code>tun0</code>, along with something like <code>inet 192.168.16.1 netmask 255.255.255.255 destination 192.168.16.2</code>. <code>ss -plunt</code> should show <code>0.0.0.0:1194</code> somewhere in the column labelled "Local Address:Port". If this is not the case, check <code>/var/log/daemon.log</code> for entries containing <code>ovpn-server</code>.

You must now copy some certificate files to your clients. As an example, if you have a Linux client named "alpha" and can access your server as root via SSH on 123.123.123.123, run the following commands as root on "alpha" (assuming OpenVPN is already installed):
<syntaxhighlight lang="bash" line>
cd /etc/openvpn
scp 123.123.123.123:/etc/openvpn/easy-rsa/pki/'{ca.crt,issued/alpha.0.crt,private/alpha.0.key,private/ta.key}' .
</syntaxhighlight>

An example of a client configuration file (save as <code>/etc/openvpn/client.conf</code>) is listed below.
<syntaxhighlight lang="cfg" line>
client
dev tun
# Use `proto udp' if that's what the server uses.
# Else use `proto tcp-client'.
proto udp
remote 123.123.123.123 1194
resolv-retry infinite
nobind

user nobody
group nobody
persist-key
persist-tun

ca /etc/openvpn/ca.crt
cert /etc/openvpn/alpha.0.crt
key /etc/openvpn/alpha.0.key

ns-cert-type server

tls-auth /etc/openvpn/ta.key 1

comp-lzo

# Uncomment the following if you want to redirect all client traffic through
# the VPN. (Without it, only 192.168.16.0/24 will be routed through the VPN.)
#redirect-gateway def1
</syntaxhighlight>

On "alpha", run <code>openvpn --config /etc/openvpn/client.conf</code> and check if it will connect. Running <code>ifconfig</code> on "alpha" should show a <code>tun0</code> with an IP in 129.168.16.0/24 and a destination of 192.168.16.1. You should be able to SSH over the VPN too, using
<syntaxhighlight lang="bash">
ssh root@192.168.16.1
</syntaxhighlight>

If this connects, your VPN works and you're done with this step!

=Step 1: PostgreSQL and Synapse=
Synapse is the name of the Matrix homeserver reference implementation, which we will be installing in this section. This procedure loosely follows [https://www.natrius.eu/dokuwiki/doku.php?id=digital:server:matrixsynapse the guide by '''natrius'''], with some key differences:
# We will thoroughly disable federation.
# We will use easy-rsa to add self-signed certificates to the Nginx reverse proxy.
# We will use <code>iptables</code> instead of <code>ufw</code>.

Before installing Synapse, first install PostgreSQL and its Python binding:
<syntaxhighlight lang="bash">
apt install postgresql python3-psycopg2
</syntaxhighlight>

Now <code>su</code> to the PostgreSQL admin account and start the PostgreSQL shell:
<syntaxhighlight lang="bash" line>
su - postgres
psql
</syntaxhighlight>

As in natrius' guide, create the synapse database and a user to own it:
<syntaxhighlight lang="sql" line>
CREATE USER "synapse" WITH PASSWORD 'password';
CREATE DATABASE synapse ENCODING 'UTF8' LC_COLLATE='C' LC_CTYPE='C' template=template0 OWNER "synapse";
\q
</syntaxhighlight>
Replace 'password' with a strong, ideally random password. That's all that's needed as far as PostgreSQL goes, so log out of the <code>postgres</code> account.

As in the aforementioned guide, first add the relevant repositories and perform any necessary updates, and then install Synapse:
<syntaxhighlight lang="bash" line>
apt install lsb-release wget apt-transport-https
wget -O /usr/share/keyrings/matrix-org-archive-keyring.gpg https://packages.matrix.org/debian/matrix-org-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/matrix-org-archive-keyring.gpg] https://packages.matrix.org/debian/ $(lsb_release -cs) main" | tee /etc/apt/sources.list.d/matrix-org.list
apt update && apt upgrade
apt install matrix-synapse-py3
</syntaxhighlight>

When asked for a hostname, enter <code>localhost</code>. Next, edit the configuration file, <code>/etc/matrix-synapse/homeserver.yaml</code>. In the <code>listeners</code> section, change the uncommented lines to the following:
<syntaxhighlight lang="yaml" line>
- port: 8008
tls: false
type: http
x_forwarded: true
bind_addresses: ['0.0.0.0']

resources:
- names: [client]
compress: false
</syntaxhighlight>
That is, we bind 0.0.0.0 (to listen to the whole network for client connections) and remove federation.

We will be even more thorough in disabling federation: search for <code>federation_domain_whitelist</code>, which (for the Debian 10 configuration file of Synapse 1.23) should be a commented line with a few domains under it. Add a new line after that comment section:
<syntaxhighlight lang="yaml">
federation_domain_whitelist: []
</syntaxhighlight>

Next scroll down to <code>federation_ip_range_blacklist</code> and remove the IPs underneath that line. Replace them with the IPv4 and IPv6 catchalls:
<syntaxhighlight lang="yaml" line>
- '0.0.0.0/0'
- '::/0'
</syntaxhighlight>

With federation now thoroughly disabled, look for <code>enable_registration: false</code> and uncomment this line. As in natrius' guide, look for <code>registration_shared_secret: <PRIVATE STRING></code>, uncomment it, and replace <code><PRIVATE STRING></code> with a long, randomly generated alphanumeric string, e.g. generated by the command
<syntaxhighlight lang="bash">
cat /dev/urandom | tr -dc 'a-zA-Z0-9' | fold -w 32 | head -n 1
</syntaxhighlight>

Write out the configuration file and exit your editor. We now need to open port 8008 to VPN clients:
<syntaxhighlight lang="bash" line>
iptables -I INPUT 1 -s 192.168.16.0/24 -i tun0 -p tcp -m tcp --dport 8008 -j ACCEPT
iptables-save >/etc/iptables/rules.v4
</syntaxhighlight>

Now start Synapse and check if it is running:
<syntaxhighlight lang="bash" line>
systemctl start matrix-synapse.service
ss -plunt
</syntaxhighlight>

The last command should show that Synapse is listening on port 8008.

You can now create an account on your homeserver:
<syntaxhighlight lang="bash">
register_new_matrix_user -c /etc/matrix-synapse/homeserver.yaml http://localhost:8008
</syntaxhighlight>
This will prompt for a username and password, as well as the shared secret you entered into the configuration file earlier.

If you have a PC or laptop that you've given access to the VPN, you can install the '''desktop''' [https://element.io/get-started Element] client on it. You should then be able to connect to <code>http://192.168.16.1:8008</code> using the account you just created. At this moment, the Android and Web clients do NOT support HTTP connections, so these clients cannot connect to your Synapse installation yet. Which brings us to...

=Step 2: Nginx and TLS=
To allow most clients to connect to your homeserver (provided they have access to the VPN), you will need to set up a reverse proxy that adds a TLS layer so they can communicate over HTTPS. While the Synapse guide by natrius recommends Let's Encrypt certificates, in a fully private context like we are considering, it makes sense to set up your own certificate authority.

I opted to build a new certificate authority in the Synapse configuration directory and reuse the configuration I picked for OpenVPN:
<syntaxhighlight lang="bash" line>
make-cadir /etc/matrix-synapse/easy-rsa
cd /etc/matrix-synapse/easy-rsa
cp /etc/openvpn/easy-rsa/vars .
./easyrsa init-pki
./easyrsa --subject-alt-name="IP:192.168.16.1" build-ca
# Choose a new CA name when prompted. The password you are prompted for
# should ideally also be different from the one you used for OpenVPN.
./easyrsa --subject-alt-name="IP:192.168.16.1" build-server-full matrix-synapse nopass
# For all clients:
./easyrsa --subject-alt-name="IP:192.168.16.1" build-client-full alpha.0 nopass
./easyrsa --subject-alt-name="IP:192.168.16.1" build-client-full bravo.0 nopass
# ...and so on
</syntaxhighlight>

Note that we are now including <code>--subject-alt-name="IP:192.168.16.1"</code> in our commands. HTTPS requires certificates to be bound to a domain or IP, and browsers tend to get ornery if they are not. We do not need Diffie-Hellman parameters now, but we do need to generate a certificate revocation list so Nginx will be able to reject revoked certificates, and we must also export our client certificates in a format browsers and mobile OSes understand:
<syntaxhighlight lang="bash" list>
# For all clients:
./easyrsa export-p12 alpha.0
./easyrsa export-p12 bravo.0
# ...and so on
./easyrsa gen-crl
</syntaxhighlight>
The export step asks you to provide a password, which allows you to securely transport the exported certificates to the clients they are to be installed on.

Next up, Nginx. Install the package, remove the default configuration, and create a new one:
<syntaxhighlight lang="bash" line>
apt install nginx
systemctl stop nginx.service
unlink /etc/nginx/sites-enabled/default
ln -s /etc/nginx/sites-available/synapse /etc/nginx/sites-enabled/synapse
editor /etc/nginx/sites-available/synapse
</syntaxhighlight>

An example configuration that sets up an HTTPS reverse proxy on port 10443 is
given below.
<syntaxhighlight lang="nginx" line>
server {
listen 10443 ssl;
server_name localhost;

ssl on;
ssl_certificate /etc/matrix-synapse/easy-rsa/pki/issued/matrix-synapse.crt;
ssl_certificate_key /etc/matrix-synapse/easy-rsa/pki/private/matrix-synapse.key;
ssl_client_certificate /etc/matrix-synapse/easy-rsa/pki/ca.crt;
ssl_crl /etc/matrix-synapse/easy-rsa/pki/crl.pem;
# Enable mutual TLS. This option provides maximal security by requiring
# per-client certificates. Unfortunately, client-side support for this
# tends to be shaky at best, so turn it off and restart Nginx if you are
# not able to connect.
ssl_verify_client on;

access_log /var/log/nginx-synapse-access_log.log;
error_log /var/log/nginx-synapse-error_log.log;

# There is no need to serve files, and we will not be using
# .well-known, since we don't use federation. So we just reverse-proxy
# Synapse's HTTP at the root and that's it.
location / {
proxy_pass http://127.0.0.1:8008;
proxy_set_header X-Forwarded-For $remote_addr;
}
}
</syntaxhighlight>

Now unblock port 10443 for the VPN and start Nginx:
<syntaxhighlight lang="bash" line>
iptables -I INPUT 1 -s 192.168.16.0/24 -i tun0 -p tcp -m tcp --dport 10443 -j ACCEPT
iptables-save >/etc/iptables/rules.v4
systemctl enable nginx.service
systemctl start nginx.service
# Check if it's running
ss -plunt
</syntaxhighlight>

The last command should show Nginx listening on port 10443. Now copy <code>/etc/matrix-synapse/easy-rsa/pki/ca.crt</code> to all clients and import it as a trusted system certificate. Also copy each <code>p12</code> certificate in <code>/etc/matrix-synapse/easy-rsa/pki/private/</code> to its respective client and import it.

The desktop and android apps should now be able to at least communicate with the server via HTTPS at <code>https://192.168.16.1:10443</code>. If, however, you get an error stating the client did not send the correct certificate, you may have to disable <code>ssl_verify_client</code> in the Nginx configuration file and restart Nginx. Note that the canonical Element-web implementation at app.element.io may not be able to talk to your server regardless; I believe this is because browsers will restrict accessing local networks from sites loaded from remote servers. Installing element-web locally will help; see Optional Extras at the end of this guide.

=Step 3: mautrix-whatsapp=
Being a rather niche package, mautrix-whatsapp is not in the Debian repositories and must be self-compiled. It also has some dependencies on versions of packages too recent to be found in the repositories of Debian 10 (buster)

First and foremost, version 1.14 of Go (<code>golang-1.14</code>) is needed at the time of writing, which has been backported to buster. If you are running buster, install Go as follows:
<syntaxhighlight lang="bash" line>
echo 'deb http://deb.debian.org/debian buster-backports main' >>/etc/apt/sources.list
apt update
apt install -t buster-backports golang
</syntaxhighlight>

Alternatively, if you are using Debian 11 (bullseye) or Unstable (sid), simply install golang directly:
<syntaxhighlight lang="bash">
apt install golang
</syntaxhighlight>

Regardless of your Debian version, you will need to install <code>ffmpeg</code>, a GNU toolchain, and <code>git</code>, if they are not already installed:
<syntaxhighlight lang="bash">
apt install ffmpeg make autoconf automake libtool gcc cmake git
</syntaxhighlight>

Next, we need to install a very recent version of <code>olm</code>, which must be hand-compiled at the time of writing. It is probably best to perform the following steps as a regular user instead of root, but I couldn't be bothered creating a new user. Caveat emptor.
<syntaxhighlight lang="bash">
cd
git clone https://gitlab.matrix.org/matrix-org/olm.git
cd olm
cmake . -Bbuild
cd build
make
# if you dropped root, use `sudo make install' here instead
make install
</syntaxhighlight>

We are now ready to compile mautrix-whatsapp. The following steps may also be executed as a regular user if you want. Clone the repo and compile:
<syntaxhighlight lang="bash" line>
cd
git clone https://github.com/tulir/mautrix-whatsapp.git
cd mautrix-whatsapp
export LD_LIBRARY_PATH=/usr/local/lib
./build.sh
# Only execute the following if you executed the above as a regular user
cd ..
sudo cp -r mautrix-whatsapp /root/mautrix-whatsapp
</syntaxhighlight>

Again as root, copy <code>/root/mautrix-whatsapp/example-config.yaml</code> to <code>/root/mautrix-whatsapp/config.yaml</code> and edit the latter.
* Under <code>homeserver</code>, set <code>address</code> to <code>http://localhost:8008</code> and <code>domain</code> to <code>localhost</code>.
* Under <code>appservice</code>, set <code>hostname</code> to <code>127.0.0.1</code>.
* Under <code>database</code> (in the <code>appservice</code> section), set <code>type</code> to <code>postgres</code> and <code>uri</code> to <code>postgres://synapse:<password>@localhost/synapse?sslmode=disable</code>, where <code><password></code> should be replaced with the PostgreSQL password you picked earlier.
* Under <code>bridge</code>, set <code>private_chat_portal_meta</code> to <code>true</code>.

The <code>permissions</code> block under <code>bridge</code> should be something like this:
<syntaxhighlight lang="yaml" line>
permissions:
"*": relaybot
"localhost": user
"@alice:localhost": admin
</syntaxhighlight>
Here <code>alice</code> should be replaced with the username you chose when issuing the <code>register_new_matrix_user</code> command in Step 1.

Finally, set <code>directory</code> under <code>logging</code> to something more suitable, like <code>/var/log/mautrix-whatsapp</code>.

Now generate the appservice registration file, copy it to the Synapse configuration directory, and change its ownership so Synapse can read it:
<syntaxhighlight lang="bash" line>
cd /root/mautrix-whatsapp
export LD_LIBRARY_PATH=/usr/local/lib
./mautrix-whatsapp -g
cp registration.yaml /etc/matrix-synapse/wa_registration.yaml
chown matrix-synapse /etc/matrix-synapse/wa_registration.yaml
</syntaxhighlight>

Edit <code>/etc/matrix-synapse/homeserver.yaml</code>. Find the line with <code>app_service_config_files</code> (which is commented out) and, below the comment, add
<syntaxhighlight lang="yaml" line>
app_service_config_files:
- "/etc/matrix-synapse/wa_registration.yaml"
</syntaxhighlight>

Now restart Synapse:
<syntaxhighlight lang="bash">
systemctl restart matrix-synapse.service
</syntaxhighlight>

It is now time to test mautrix-whatsapp. For testing purposes, start the bridge in the foreground:
<syntaxhighlight lang="bash">
/root/mautrix-whatsapp/mautrix-whatsapp
</syntaxhighlight>

Connect to your homeserver with Element-Desktop or Element-Android and start a direct chat with <code>@whatsappbot:localhost</code>. You should get a message saying the room has been set up as the bridge management/status room. Type <code>help</code> and send the message. If the bot replies, you're good; if not, check the logs, and check/adjust your configuration carefully and restart Synapse and mautrix-whatsapp.

If all is working, go back to the terminal where you started <code>/root/mautrix-whatsapp/mautrix-whatsapp</code> and terminate the process with Ctrl-C. Now create a new file <code>/etc/systemd/system/mautrix-whatsapp.service</code> and enter the following:
<syntaxhighlight lang="ini" line>
[Unit]
Description=WhatsApp to Matrix bridge
Wants=matrix-synapse.service

[Service]
Type=exec
Environment="LD_LIBRARY_PATH=/usr/local/lib"
WorkingDirectory=/root/mautrix-whatsapp
ExecStart=/root/mautrix-whatsapp/mautrix-whatsapp
Restart=always
RestartSec=10
SyslogIdentifier=mautrix-whatsapp

[Install]
WantedBy=multi-user.target
</syntaxhighlight>

You should now be able to start mautrix-whatsapp using systemd:
<syntaxhighlight lang="bash" line>
systemctl start mautrix-whatsapp.service
systemctl enable mautrix-whatsapp.service
</syntaxhighlight>

Wait a few seconds for mautrix-whatsapp to finish loading, then message <code>help</code> to your bot again to make sure it still works. If it does, send it <code>login</code>, and use the actual (official) WhatsApp client to scan the WhatsApp Web QR code that the bot sends you. It should immediately start pulling a few chats, but most likely not your entire history. Ignore it for now. Open your Element client's settings, go to Help & Advanced, and find your access token. Copy it. Then send the bridge bot <code>login-matrix <access_token></code>, replacing <code><access_token></code> with the access token you just copied. This will enable double puppeting; see [https://github.com/tulir/mautrix-whatsapp/wiki/Authentication the Authentication guide].

If you are not content with the meagre amount of chats/messages pulled by the bot, go into each room it created and send <code>!wa delete-portal</code>. Then go back to your terminal/SSH session and edit <code>/root/mautrix-whatsapp/config.yaml</code> again. In the <code>bridge</code> section, edit these settings:
* <code>initial_chat_sync_count</code> -- this is the amount of WhatsApp group portals that should be created. You probably want to set this to at least the number of WhatsApp groups you're in, including "one-on-one" groups for people you've direct-messaged. If unsure, just pick a number that's definitely larger than that.
* <code>initial_history_fill_count</code> -- this is the amount of old messages that will be fetched. If you have some very active or old rooms, you will need a very large number here. One caveat: mautrix-whatsapp can get a bit wonky if it's syncing a large amount of messages, and may need to be killed and restarted a few times for the process to complete. That means you should also be monitoring the sync process.
* <code>sync_max_chat_age</code> -- this is the age cutoff in seconds for synced messages. Set it to something like 2000000000 (two billion seconds, or roughly 63 years) to effectively disable the age cutoff.
* <code>initial_history_disable_notifications</code> -- this determines whether you get a "new message" notification for every synced old message. If you set <code>initial_history_fill_count</code> to a large number, do yourself a ''huge'' favour and set this to <code>true</code>.

Now restart mautrix-whatsapp:
<syntaxhighlight lang="bash">
systemctl restart mautrix-whatsapp.service
</syntaxhighlight>

Finally, send the bridge bot <code>sync --create-all</code>. It will now start to pull the chats you chose. Bear in mind that this can take a very long time. If you notice it stops making progress, restart mautrix-whatsapp and send <code>sync --create-all</code> again: it will continue at the point it was stopped.

You are now basically done, although you probably still have WhatsApp running on your phone. The next step will explain how to migrate it to a VM.

=Step 4: migrate WhatsApp proper to a VM=
I have not performed this step yet myself. However, [https://github.com/tulir/mautrix-whatsapp/wiki/Android-VM-Setup the official guide by '''Alistair Francis'''] should be easy enough to follow. I will update this guide when I've done this myself.

N.B. in my current setup, WhatsApp runs on a [https://lineageos.org/ LineageOS] phone, and its traffic is piped through the VPN.

=Step 5: optional extras=
Finally, there are a few things you can do to extend this setup.

==Redirect port 443 to OpenVPN==
Some public Wi-Fi networks only allow access to a very restricted set of ports so clients are limited to web-browsing and checking email. This annoying bit of shit-tier network administration is easily circumvented by piping your traffic through a VPN, which, of course, you just set up -- but you have to be able to connect to the VPN in the first place, and port 1194 (OpenVPN's default port) is practically guaranteed to be blocked by such networks. Luckily, the default HTTPS port, TCP 443, is practically guaranteed to NOT be blocked, so if your OpenVPN server is using TCP, you can just redirect traffic from 443 to 1194 and log in to your VPN on basically any network. ''N.B. switch your OpenVPN over to TCP if you want to do this but chose UDP earlier.''

A few commands are all that's needed:
<syntaxhighlight lang="bash" line>
iptables -A PREROUTING -i eth0 -p tcp -m tcp --dport 443 -j REDIRECT --to-ports 1194
iptables -I INPUT 1 -p tcp -m tcp --dport 443 -j ACCEPT
iptables-save >/etc/iptables/rules.v4
</syntaxhighlight>

You can now use <code>remote 123.123.123.123 443</code> in your client configuration files. Also be sure to add <code>redirect-gateway def1</code> on clients that connect to public Wi-Fi!

==Install element-web==
The official element-web implementation at app.element.io does not work with a private homeserver, but element-web ''will'' work if you install it on your homeserver. '''Note that the authors of element-web specifically recommend against running element-web on the same domain as the homeserver.''' However, as access is limited to the VPN, the risk should be limited as long as only trusted and experienced users are allowed access to the VPN in the first place.

Download the latest release (1.75-rc1 at the time of writing; replace the version as necessary in what follows, obviously) from [https://github.com/vector-im/element-web/releases], extract it, move it to the proper place, and create the config file:
<syntaxhighlight lang="bash" line>
wget https://github.com/vector-im/element-web/releases/download/v1.7.15-rc.1/element-v1.7.15-rc.1.tar.gz
tar -xvzf element-v1.7.15-rc.1.tar.gz
mv element-v1.7.15-rc.1 /var/www/element-web
cd /var/www/element-web
cp config.sample.json config.json
</syntaxhighlight>

Edit <code>config.json</code>. Set <code>"base_url"</code> to <code>"https://192.168.16.1:10443"</code> and <code>"server_name"</code> to <code>"localhost"</code> in the <code>"m.homeserver"</code> block near the top. In the root block, set <code>"disable_custom_urls"</code> to <code>true</code> and <code>"default_federate"</code> to <code>false</code>.

Since we've already set up Nginx, we can just tell it to serve element-web as well, and we can even reuse the certificate authority. Edit the configuration file you created earlier, <code>/etc/nginx/sites-available/synapse</code> and add the following block at the end:
<syntaxhighlight lang="nginx" line>
server {
listen 10444 ssl;
server_name localhost;

root /var/www/element-web;
index index.html;

ssl on;
ssl_certificate /etc/matrix-synapse/easy-rsa/pki/issued/element-web.crt;
ssl_certificate_key /etc/matrix-synapse/easy-rsa/pki/private/element-web.key;
ssl_client_certificate /etc/matrix-synapse/easy-rsa/pki/ca.crt;
ssl_crl /etc/matrix-synapse/easy-rsa/pki/crl.pem;
ssl_verify_client on;

access_log /var/log/nginx-element-web-access_log.log;
error_log /var/log/nginx-element-web-error_log.log;
}
</syntaxhighlight>

If you did not manage to get <code>ssl_verify_client</code> to work earlier, remove that line here too. Also, if you did not use port 443 for OpenVPN, you may use <code>listen 443 ssl;</code> instead of <code>listen 10444 ssl;</code> if you want (so you can just point your browser at https://192.168.16.1). Finally, add an iptables rule to allow connecting from within the VPN, and restart Nginx:
<syntaxhighlight lang="bash" line>
# Replace 10444 with 443 if necessary
iptables -I INPUT 1 -s 192.168.16.0/24 -i tun0 -p tcp -m tcp --dport 10444 -j ACCEPT
iptables-save >/etc/iptables/rules.v4
systemctl restart nginx.service
</syntaxhighlight>

==Block Facebook on clients==
On all clients (except the phone running WhatsApp, if you have not moved it to a VM on the server yet), you can now completely block all Facebook-owned IPs and still retain access to WhatsApp using your Matrix homeserver. While tedious to do by hand (considering Facebook's IP pool grows like an aggressive tumour), it is easily automated on Linux with a cron job and iptables.

First of all, create a new iptables chain that will be used for automated IP blocking, and add it to the front of your INPUT and OUTPUT chains:
<syntaxhighlight lang="bash" line>
iptables -N BLOCK
iptables -I INPUT 1 -j BLOCK
iptables -I OUTPUT 1 -j BLOCK
</syntaxhighlight>

Next, we will create a script that finds the list of IPs owned by Facebook and adds them to the BLOCK chain. N.B. this requires <code>whois</code>, which should be available in any package manager under that name, so install it first if necessary. Then create the file <code>/etc/cron.hourly/ipblock.sh</code> with the following contents:
<syntaxhighlight lang="bash" line>
#!/bin/bash
iptables=/sbin/iptables

$iptables -F BLOCK

asns="AS32934"
for asn in asns
do
ips="$(whois -h whois.radb.net -- -i origin -T route $asn | grep route: | awk '{print $2}')"
for i in $ips
do
$iptables -A BLOCK -d $i -j REJECT --reject-with icmp-host-unreachable
$iptables -A BLOCK -s $i -j REJECT --reject-with icmp-host-unreachable
done
done
</syntaxhighlight>

This script queries whois.radb.net to find all IPs registered under the [https://en.wikipedia.org/wiki/Autonomous_system_(Internet) autonomous system number] AS32934, which is Facebook. You may add other ASNs too if you want. Note that although the list "only" contains 200 entries or so (at the time of writing), they include mask bits in CIDR notation: this list in fact represents tens of thousands of IP addresses, all owned by Facebook.

Make sure to make the script executable, and run it once if you don't want to wait until the next hour for cron to do it.
<syntaxhighlight lang="bash" line>
chmod +x /etc/cron.hourly/ipblock.sh
/etc/cron.hourly/ipblock.sh
iptables-save >/etc/iptables/rules.v4
</syntaxhighlight>

==Honourable mention: Pi-hole==
This is an honourable mention because I will not describe the installation process here and it is not related to mautrix-whatsapp. Nevertheless, as following this guide leaves you with a perfectly usable VPN server, and people reading this are likely to be privacy-conscious, I feel it is worthwhile to link [https://pi-hole.net/ Pi-hole] here. Pi-hole is a very powerful ad-blocking framework acting at DNS level. Like Synapse, you can configure Pi-hole to only be accessible to clients inside your VPN (by allowing only connections from 192.168.16.0/24 on device tun0). On your VPN clients, you can set 192.168.16.1 as your primary DNS server, so all clients are protected from malicious ads when connected to the VPN.

==Honourable mention: Tor proxy==
Your VPS can also serve as a VPN-wide proxy that sends traffic through [https://www.torproject.org/ Tor]. [https://www.marcus-povey.co.uk/2016/03/24/using-tor-as-a-http-proxy/ '''Marcus Povey''' has created a guide on how to set up a Tor proxy with polipo.]

Considering Tor's abysmal transfer speed, you probably don't ''always'' want to redirect traffic over Tor. Most browsers support [https://en.wikipedia.org/wiki/Proxy_auto-config proxy auto-config] (PAC), which allows you to fine-tune which sites get piped through the proxy. For example, the following PAC uses the Tor proxy to handle [https://en.wikipedia.org/wiki/.onion .onion] domains:
<syntaxhighlight lang="javascript" line>
function FindProxyForURL (url, host)
{
if (shExpMatch (host, "*.onion"))
{
return "PROXY 192.168.16.1:8123"
}
return "DIRECT;"
}
</syntaxhighlight>

Much more advanced configurations are possible with proxy auto-config, e.g. redirecting all HTTP traffic but not HTTPS, whitelisting/blacklisting domains.

Main Page

2020-12-12T10:22:46Z

Link:

Welcome to '''Penguin Development'''! We make [[w:free and open-source software|free and open-source software]] and [[w:Open-source hardware|hardware]].

See below for current releases. All software and hardware is licensed under the [https://gnu.org/licenses/gpl.html GPL] (version 3 or higher) unless otherwise stated.

=Software=
* [[AUTOMOME]] — the OTTish AUTOMEME clone
* [[Ising]] — Monte Carlo Ising model simulator
* [[stackermann]] — a stack-based [[w:Ackermann function|Ackermann function]] calculator

=Hardware=
* [[timelapse]] — time-lapse trigger for digital cameras

=Code snippets and how-tos=
* [[Animated 3D plotting with Blender]]
* [[Matrix Synapse and mautrix-whatsapp in a VPN]]

=Other=
* [[LineageOS builds|Unofficial LineageOS builds]]

Matrix Synapse and mautrix-whatsapp in a VPN

2020-12-12T10:21:02Z

Link: Created page with "'''WhatsApp''' is a popular communication app for Android and iOS. It is owned by Facebook, which has a hostile attitude towards alternative clients and open source software,..."

'''WhatsApp''' is a popular communication app for Android and iOS. It is owned by Facebook, which has a hostile attitude towards alternative clients and open source software, along with [https://stallman.org/facebook.html being notorious for its egregious privacy violations (and de-facto support of white supremacy and fascism)]. It stands to reason, then, that WhatsApp is not an app that any privacy-conscious individual should want to have installed on their mobile phone, which typically holds a vast quantity of personal data. However, the unfortunate truth is that it tends to be virtually impossible for many of us to stop using WhatsApp without permanently losing contact with several friends, family members, clients or colleagues. Thus, one may seek to find a middle ground: keeping WhatsApp well away from one's personal devices, but somehow still connecting to its network using these devices. Given Facebook's hostile attitude to third-party clients, one might expect such a task to be impossible... or is it?

'''Enter the Matrix.''' [https://matrix.org/ Matrix] is a free (as in speech), feature-rich decentralised communication ecosystem that can serve as a platform for instant messaging, e.g. using [https://www.element.io/ Element] as a client. Although I would highly encourage switching from WhatsApp to Element whenever possible, it turns out Matrix is in fact capable of communicating with the WhatsApp network. This is done using [https://github.com/tulir/mautrix-whatsapp mautrix-whatsapp], which masquerades as a WhatsApp Web client and uses it to communicate with the actual WhatsApp client running on a phone or emulator.

'''A note:''' this guide is essentially an amalgamation of the most relevant bits of various other guides: [https://wiki.debian.org/OpenVPN the Debian OpenVPN guide], [https://openvpn.net/community-resources/how-to/#installing-openvpn the OpenVPN community installation guide], [https://www.natrius.eu/dokuwiki/doku.php?id=digital:server:matrixsynapse the Synapse installation guide by '''natrius'''], the [https://gist.github.com/marcopaganini/0823d31d43557f9711e21b43a3223fce Nginx/TLS reverse proxy guide by '''Marco Paganini'''], [http://blog.hoxnox.com/inet/ssl_nginx.md.html the Nginx/easy-rsa guide by '''hoxnox'''], and the [https://github.com/tulir/mautrix-whatsapp/wiki/Bridge-setup official mautrix-whatsapp bridge setup guide by '''Tulir Asokan''']. These individual guides explain their steps in greater depth than I do here, and I highly, highly recommend reading through all of them before tackling a project like this one. '''Also be very aware that I am not an expert in any of this. If you need enterprise-grade security, close this browser tab now and consult an actual expert.''' That said, I have made an honest attempt to hammer down any security holes I could think of, and I am presently running this set-up myself.

=The set-up=
[[File:Mautrix-whatsapp-setup-pathified.svg]]

This guide will explain one possible configuration to use WhatsApp from a Matrix client. In this configuration, a Matrix homeserver (Synapse) and mautrix-whatsapp will be installed on a (virtual) private server, along with OpenVPN. The setup is completely contained within the virtual private network (VPN) created by OpenVPN, and does not require any entrypoints from the outside world except through the VPN (although you may want to enable SSH access for setup and administration). It therefore has a high degree of inherent security. A reverse HTTPS proxy is set up using Nginx with certificates generated by easy-rsa: this is necessary for some clients to be able to connect.

<code>iptables</code> is used for setting up routing and firewalling of the server, and only IPv4 is considered for the time being. I wish to ''eventually'' migrate to <code>nftables</code> and a dual IPv4/IPv6 stack, however this will take more time and effort than I have available, especially considering the current setup "just works" for me.

This guide is primarily focussed on a "single owner, multiple devices" configuration: extra security precautions should be taken if one wants to allow multiple individuals in the VPN, and using multiple WhatsApp accounts in particular is beyond the scope of this guide.

N.B. it is up to you to decide where WhatsApp (the actual proprietary app) goes in the graphic above: as shown, it is put on the VPS (in an emulator or VM), but it is also possible to leave it off the VPS, e.g. running on a normal phone. Off the VPS, you additionally have the choice of whether you want to route its traffic through the VPN (recommended) or not.

==Requirements==
* A WhatsApp account, and the WhatsApp app running either on a phone or in an emulator on a device with a webcam
* A (virtual) private server ((V)PS) with the following specs:
** A static IPv4 address
** Linux, ideally Debian 10
** root/<code>sudo</code> access
** At least 1 GB RAM
** At least 5 GB disk space for the software and text message storage
** More disk space for the media (videos, etc.) you send and receive
* Decent knowledge of Linux administration
* A free weekend or so to set up, test and tweak everything

The environment used in this guide is a VPS running Debian 10 with full root access; all commands are run as root unless otherwise stated. It is assumed that the VPS is in a fresh-off-the-shelf state with little more than <code>sshd</code> installed and running.

=Step 0: iptables and OpenVPN=
The first and foremost things to get working are the firewall and VPN server. ''Henceforth, we shall use '''192.168.16.0/24''' as the OpenVPN address space, and '''port 1194''' (UDP or TCP) as the OpenVPN port. Take extra care if you want to use something else. We shall use '''123.123.123.123''' as the externally reachable IP of the server; always replace this by whatever the actual address is.''

Log in to your VPS and install iptables as follows:
<syntaxhighlight lang="bash">
apt install iptables iptables-persistent
</syntaxhighlight>

Let us begin by setting up some basic security:
<syntaxhighlight lang="bash" line>
iptables -A INPUT -i lo -j ACCEPT
iptables -A INPUT -s 127.0.0.1/32 -j ACCEPT
iptables -A INPUT -m state --state RELATED,ESTABLISHED -j ACCEPT
iptables -A INPUT -p icmp -m icmp --icmp-type 8 -j ACCEPT
iptables -A INPUT -p icmp -m icmp --icmp-type 11 -j ACCEPT
iptables -A INPUT -p icmp -m icmp --icmp-type 3 -j ACCEPT
iptables -A INPUT -p tcp -m tcp --dport 22 -j ACCEPT
iptables -A INPUT -j DROP
iptables-save >/etc/iptables/rules.v4
</syntaxhighlight>

This will drop all incoming connections apart from SSH and a few ICMP messages. The last line preserves your iptables rules when rebooting.

The next step is to install OpenVPN. The instructions provided here mostly follow [https://wiki.debian.org/OpenVPN Debian's OpenVPN guide]; see that page for more in-depth information. Start by installing the required packages:
<syntaxhighlight lang="bash">
apt install easy-rsa openvpn
</syntaxhighlight>
Next, we create a certificate authority directory in <code>/etc/openvpn</code> and edit the config:
<syntaxhighlight lang="bash" line>
make-cadir /etc/openvpn/easy-rsa
cd /etc/openvpn/easy-rsa
editor vars
</syntaxhighlight>

The <code>vars</code> file has sensible defaults, but you may want to make a few changes (see the inline documentation if you are unsure):
# uncomment the line with <code>set_var EASYRSA_DN "cn_only"</code>
# set the key size to 4096: <code>set_var EASYRSA_KEY_SIZE 4096</code>
# set the CA validity to something long, like 10 years: <code>set_var EASYRSA_CA_EXPIRE 3650</code>
# set the certificate validity to something similar: <code>set_var EASYRSA_CERT_EXPIRE 3650</code>

After writing the vars file, create the certificate authority, a server certificate and Diffie-Hellman parameters:
<syntaxhighlight lang="bash" line>
./easyrsa init-pki
./easyrsa build-ca
./easyrsa build-server-full server nopass
./easyrsa gen-dh
</syntaxhighlight>
The <code>build-ca</code> step will prompt you for a name and password. The name can be whatever you like, e.g. "My OpenVPN CA". Choose something strong but memorable as the password. Every further interaction with the certificate authority will require this password.

Now create a certificate for every client (desktop, laptop, tablet, mobile phone, refrigerator...) you want to have access to the VPN/your WhatsApp account. It's a good idea to use a file name that allows you to tell these certificates apart, e.g. <code>hostname.n</code>, where <code>hostname</code> is the hostname of the device and <code>n</code> is a number indicating this is the n'th certificate issued for that hostname:
<syntaxhighlight lang="bash" line>
./easyrsa build-client-full alpha.0 nopass
./easyrsa build-client-full bravo.0 nopass
# And so on...
</syntaxhighlight>

Finally, per the [https://openvpn.net/community-resources/how-to/#installing-openvpn OpenVPN community installation guide], generate a shared secret TLS key:
<syntaxhighlight lang="bash" line>
cd /etc/openvpn/easy-rsa/pki/private
openvpn --genkey --secret ta.key
</syntaxhighlight>

Now edit the OpenVPN configuration file:
<syntaxhighlight lang="bash" line>
cd /etc/openvpn
editor server.conf
</syntaxhighlight>

A viable example configuration file follows. See <code>openvpn(8)</code> if it is unclear what an option does. Be sure to save this file as /etc/openvpn/server.conf.
<syntaxhighlight lang="cfg" line>
mode server
# Enable TLS encryption.
tls-server
# Listen on port 1194 (the default).
port 1194
# Set the protocol here. UDP is the default, but it may give you trouble
# connecting on low-quality public Wi-Fi. You can use `proto tcp-server'
# here instead, but note that this causes extra overhead.
# Choose `proto tcp-server' if you want to redirect port 443 to OpenVPN
# to allow connecting over some poorly configured public WiFi networks.
proto udp

# Use TUN device, as opposed to TAP. In 99% of cases, TUN is what you want.
# TAP configuration is outside the scope of this article.
dev tun
# IP pool to be used for OpenVPN. The parameters as given will put the server
# at 192.168.16.1 and clients at addresses up to 192.168.16.255.
server 192.168.16.0 255.255.255.0

# ca.crt file of the certificate authority we just set up.
ca /etc/openvpn/easy-rsa/pki/ca.crt
# Server certificate.
cert /etc/openvpn/easy-rsa/pki/issued/server.crt
# Server private key.
key /etc/openvpn/easy-rsa/pki/private/server.key
# Diffie-Hellman parameters.
dh /etc/openvpn/easy-rsa/pki/dh.pem
# TLS key.
tls-auth /etc/openvpn/easy-rsa/pki/private/ta.key 0

# Timeout parameters for sending pings/restarting OpenVPN. See openvpn(8).
keepalive 20 120
# Enable the following if you want clients to be able to address
# one another directly.
#client-to-client

# Compress the stream with LZO to limit bandwidth.
comp-lzo
# Allow at most 10 clients to connect at the same time.
# Increase if necessary, but make sure your network and server can handle
# the load.
max-clients 10

# Drop root privileges.
user nobody
group nogroup

# Persist keys and TUN device across restarts, since we are dropping root.
persist-key
persist-tun

# Status file.
status /var/log/openvpn-status.log
</syntaxhighlight>

Next, configure the firewall to allow OpenVPN clients. The first step depends on the protocol you chose set in the OpenVPN server configuration. If you chose UDP:
<syntaxhighlight lang="bash">
iptables -I INPUT 1 -p udp -m udp --dport 1194 -j ACCEPT
</syntaxhighlight>
OR, if you chose TCP:
<syntaxhighlight lang="bash">
iptables -I INPUT 1 -p tcp -m tcp --dport 1194 -j ACCEPT
</syntaxhighlight>

Next, set up forwarding and masquerading, and start the server! N.B. it is assumed here that the ethernet device of your server is eth0, and that OpenVPN creates the device <code>tun0</code> (i.e. nothing else sets up a TUN device before OpenVPN). Change tun0 and/or eth0 as necessary if this is not true.
<syntaxhighlight lang="bash" line>
iptables -A FORWARD -i tun0 -j ACCEPT
iptables -A FORWARD -i tun0 -o eth0 -m state --state RELATED,ESTABLISHED -j ACCEPT
iptables -A FORWARD -i eth0 -o tun0 -m state --state RELATED,ESTABLISHED -j ACCEPT
iptables -A POSTROUTING -s 192.168.16.0/24 -o eth0 -j MASQUERADE
iptables-save >/etc/iptables/rules.v4
echo "net.ipv4.ip_forward = 1" >>/etc/sysctl.conf
sysctl -p
systemctl enable openvpn.service
systemctl restart openvpn.service
ifconfig
ss -plunt
</syntaxhighlight>

Make sure OpenVPN starts correctly: <code>ifconfig</code> should show <code>tun0</code>, along with something like <code>inet 192.168.16.1 netmask 255.255.255.255 destination 192.168.16.2</code>. <code>ss -plunt</code> should show <code>0.0.0.0:1194</code> somewhere in the column labelled "Local Address:Port". If this is not the case, check <code>/var/log/daemon.log</code> for entries containing <code>ovpn-server</code>.

You must now copy some certificate files to your clients. As an example, if you have a Linux client named "alpha" and can access your server as root via SSH on 123.123.123.123, run the following commands as root on "alpha" (assuming OpenVPN is already installed):
<syntaxhighlight lang="bash" line>
cd /etc/openvpn
scp 123.123.123.123:/etc/openvpn/easy-rsa/pki/'{ca.crt,issued/alpha.0.crt,private/alpha.0.key,private/ta.key}' .
</syntaxhighlight>

An example of a client configuration file (save as <code>/etc/openvpn/client.conf</code>) is listed below.
<syntaxhighlight lang="cfg" line>
client
dev tun
# Use `proto udp' if that's what the server uses.
# Else use `proto tcp-client'.
proto udp
remote 123.123.123.123 1194
resolv-retry infinite
nobind

user nobody
group nobody
persist-key
persist-tun

ca /etc/openvpn/ca.crt
cert /etc/openvpn/alpha.0.crt
key /etc/openvpn/alpha.0.key

ns-cert-type server

tls-auth /etc/openvpn/ta.key 1

comp-lzo

# Uncomment the following if you want to redirect all client traffic through
# the VPN. (Without it, only 192.168.16.0/24 will be routed through the VPN.)
#redirect-gateway def1
</syntaxhighlight>

On "alpha", run <code>openvpn --config /etc/openvpn/client.conf</code> and check if it will connect. Running <code>ifconfig</code> on "alpha" should show a <code>tun0</code> with an IP in 129.168.16.0/24 and a destination of 192.168.16.1. You should be able to SSH over the VPN too, using
<syntaxhighlight lang="bash">
ssh root@192.168.16.1
</syntaxhighlight>

If this connects, your VPN works and you're done with this step!

=Step 1: PostgreSQL and Synapse=
Synapse is the name of the Matrix homeserver reference implementation, which we will be installing in this section. This procedure loosely follows [https://www.natrius.eu/dokuwiki/doku.php?id=digital:server:matrixsynapse the guide by '''natrius'''], with some key differences:
# We will thoroughly disable federation.
# We will use easy-rsa to add self-signed certificates to the Nginx reverse proxy.
# We will use <code>iptables</code> instead of <code>ufw</code>.

Before installing Synapse, first install PostgreSQL and its Python binding:
<syntaxhighlight lang="bash">
apt install postgresql python3-psycopg2
</syntaxhighlight>

Now <code>su</code> to the PostgreSQL admin account and start the PostgreSQL shell:
<syntaxhighlight lang="bash" line>
su - postgres
psql
</syntaxhighlight>

As in natrius' guide, create the synapse database and a user to own it:
<syntaxhighlight lang="sql" line>
CREATE USER "synapse" WITH PASSWORD 'password';
CREATE DATABASE synapse ENCODING 'UTF8' LC_COLLATE='C' LC_CTYPE='C' template=template0 OWNER "synapse";
\q
</syntaxhighlight>
Replace 'password' with a strong, ideally random password. That's all that's needed as far as PostgreSQL goes, so log out of the <code>postgres</code> account.

As in the aforementioned guide, first add the relevant repositories and perform any necessary updates, and then install Synapse:
<syntaxhighlight lang="bash" line>
apt install lsb-release wget apt-transport-https
wget -O /usr/share/keyrings/matrix-org-archive-keyring.gpg https://packages.matrix.org/debian/matrix-org-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/matrix-org-archive-keyring.gpg] https://packages.matrix.org/debian/ $(lsb_release -cs) main" | tee /etc/apt/sources.list.d/matrix-org.list
apt update && apt upgrade
apt install matrix-synapse-py3
</syntaxhighlight>

When asked for a hostname, enter <code>localhost</code>. Next, edit the configuration file, <code>/etc/matrix-synapse/homeserver.yaml</code>. In the <code>listeners</code> section, change the uncommented lines to the following:
<syntaxhighlight lang="yaml" line>
- port: 8008
tls: false
type: http
x_forwarded: true
bind_addresses: ['0.0.0.0']

resources:
- names: [client]
compress: false
</syntaxhighlight>
That is, we bind 0.0.0.0 (to listen to the whole network for client connections) and remove federation.

We will be even more thorough in disabling federation: search for <code>federation_domain_whitelist</code>, which (for the Debian 10 configuration file of Synapse 1.23) should be a commented line with a few domains under it. Add a new line after that comment section:
<syntaxhighlight lang="yaml">
federation_domain_whitelist: []
</syntaxhighlight>

Next scroll down to <code>federation_ip_range_blacklist</code> and remove the IPs underneath that line. Replace them with the IPv4 and IPv6 catchalls:
<syntaxhighlight lang="yaml" line>
- '0.0.0.0/0'
- '::/0'
</syntaxhighlight>

With federation now thoroughly disabled, look for <code>enable_registration: false</code> and uncomment this line. As in natrius' guide, look for <code>registration_shared_secret: <PRIVATE STRING></code>, uncomment it, and replace <code><PRIVATE STRING></code> with a long, randomly generated alphanumeric string, e.g. generated by the command
<syntaxhighlight lang="bash">
cat /dev/urandom | tr -dc 'a-zA-Z0-9' | fold -w 32 | head -n 1
</syntaxhighlight>

Write out the configuration file and exit your editor. We now need to open port 8008 to VPN clients:
<syntaxhighlight lang="bash" line>
iptables -I INPUT 1 -s 192.168.16.0/24 -i tun0 -p tcp -m tcp --dport 8008 -j ACCEPT
iptables-save >/etc/iptables/rules.v4
</syntaxhighlight>

Now start Synapse and check if it is running:
<syntaxhighlight lang="bash" line>
systemctl start matrix-synapse.service
ss -plunt
</syntaxhighlight>

The last command should show that Synapse is listening on port 8008.

You can now create an account on your homeserver:
<syntaxhighlight lang="bash">
register_new_matrix_user -c /etc/matrix-synapse/homeserver.yaml http://localhost:8008
</syntaxhighlight>
This will prompt for a username and password, as well as the shared secret you entered into the configuration file earlier.

If you have a PC or laptop that you've given access to the VPN, you can install the '''desktop''' [https://element.io/get-started Element] client on it. You should then be able to connect to <code>http://192.168.16.1:8008</code> using the account you just created. At this moment, the Android and Web clients do NOT support HTTP connections, so these clients cannot connect to your Synapse installation yet. Which brings us to...

=Step 2: Nginx and TLS=
To allow most clients to connect to your homeserver (provided they have access to the VPN), you will need to set up a reverse proxy that adds a TLS layer so they can communicate over HTTPS. While the Synapse guide by natrius recommends Let's Encrypt certificates, in a fully private context like we are considering, it makes sense to set up your own certificate authority.

I opted to build a new certificate authority in the Synapse configuration directory and reuse the configuration I picked for OpenVPN:
<syntaxhighlight lang="bash" line>
make-cadir /etc/matrix-synapse/easy-rsa
cd /etc/matrix-synapse/easy-rsa
cp /etc/openvpn/easy-rsa/vars .
./easyrsa init-pki
./easyrsa --subject-alt-name="IP:192.168.16.1" build-ca
# Choose a new CA name when prompted. The password you are prompted for
# should ideally also be different from the one you used for OpenVPN.
./easyrsa --subject-alt-name="IP:192.168.16.1" build-server-full matrix-synapse nopass
# For all clients:
./easyrsa --subject-alt-name="IP:192.168.16.1" build-client-full alpha.0 nopass
./easyrsa --subject-alt-name="IP:192.168.16.1" build-client-full bravo.0 nopass
# ...and so on
</syntaxhighlight>

Note that we are now including <code>--subject-alt-name="IP:192.168.16.1"</code> in our commands. HTTPS requires certificates to be bound to a domain or IP, and browsers tend to get ornery if they are not. We do not need Diffie-Hellman parameters now, but we do need to generate a certificate revocation list so Nginx will be able to reject revoked certificates, and we must also export our client certificates in a format browsers and mobile OSes understand:
<syntaxhighlight lang="bash" list>
# For all clients:
./easyrsa export-p12 alpha.0
./easyrsa export-p12 bravo.0
# ...and so on
./easyrsa gen-crl
</syntaxhighlight>
The export step asks you to provide a password, which allows you to securely transport the exported certificates to the clients they are to be installed on.

Next up, Nginx. Install the package, remove the default configuration, and create a new one:
<syntaxhighlight lang="bash" line>
apt install nginx
systemctl stop nginx.service
unlink /etc/nginx/sites-enabled/default
ln -s /etc/nginx/sites-available/synapse /etc/nginx/sites-enabled/synapse
editor /etc/nginx/sites-available/synapse
</syntaxhighlight>

An example configuration that sets up an HTTPS reverse proxy on port 10443 is
given below.
<syntaxhighlight lang="nginx" line>
server {
listen 10443 ssl;
server_name localhost;

ssl on;
ssl_certificate /etc/matrix-synapse/easy-rsa/pki/issued/matrix-synapse.crt;
ssl_certificate_key /etc/matrix-synapse/easy-rsa/pki/private/matrix-synapse.key;
ssl_client_certificate /etc/matrix-synapse/easy-rsa/pki/ca.crt;
ssl_crl /etc/matrix-synapse/easy-rsa/pki/crl.pem;
# Enable mutual TLS. This option provides maximal security by requiring
# per-client certificates. Unfortunately, client-side support for this
# tends to be shaky at best, so turn it off and restart Nginx if you are
# not able to connect.
ssl_verify_client on;

access_log /var/log/nginx-synapse-access_log.log;
error_log /var/log/nginx-synapse-error_log.log;

# There is no need to serve files, and we will not be using
# .well-known, since we don't use federation. So we just reverse-proxy
# Synapse's HTTP at the root and that's it.
location / {
proxy_pass http://127.0.0.1:8008;
proxy_set_header X-Forwarded-For $remote_addr;
}
}
</syntaxhighlight>

Now unblock port 10443 for the VPN and start Nginx:
<syntaxhighlight lang="bash" line>
iptables -I INPUT 1 -s 192.168.16.0/24 -i tun0 -p tcp -m tcp --dport 10443 -j ACCEPT
iptables-save >/etc/iptables/rules.v4
systemctl enable nginx.service
systemctl start nginx.service
# Check if it's running
ss -plunt
</syntaxhighlight>

The last command should show Nginx listening on port 10443. Now copy <code>/etc/matrix-synapse/easy-rsa/pki/ca.crt</code> to all clients and import it as a trusted system certificate. Also copy each <code>p12</code> certificate in <code>/etc/matrix-synapse/easy-rsa/pki/private/</code> to its respective client and import it.

The desktop and android apps should now be able to at least communicate with the server via HTTPS at <code>https://192.168.16.1:10443</code>. If, however, you get an error stating the client did not send the correct certificate, you may have to disable <code>ssl_verify_client</code> in the Nginx configuration file and restart Nginx. Note that the canonical Element-web implementation at app.element.io may not be able to talk to your server regardless; I believe this is because browsers will restrict accessing local networks from sites loaded from remote servers. Installing element-web locally will help; see Optional Extras at the end of this guide.

=Step 3: mautrix-whatsapp=
Being a rather niche package, mautrix-whatsapp is not in the Debian repositories and must be self-compiled. It also has some dependencies on versions of packages too recent to be found in the repositories of Debian 10 (buster)

First and foremost, version 1.14 of Go (<code>golang-1.14</code>) is needed at the time of writing, which has been backported to buster. If you are running buster, install Go as follows:
<syntaxhighlight lang="bash" line>
echo 'deb http://deb.debian.org/debian buster-backports main' >>/etc/apt/sources.list
apt update
apt install -t buster-backports golang
</syntaxhighlight>

Alternatively, if you are using Debian 11 (bullseye) or Unstable (sid), simply install golang directly:
<syntaxhighlight lang="bash">
apt install golang
</syntaxhighlight>

Regardless of your Debian version, you will need to install <code>ffmpeg</code>, a GNU toolchain, and <code>git</code>, if they are not already installed:
<syntaxhighlight lang="bash">
apt install ffmpeg make autoconf automake libtool gcc cmake git
</syntaxhighlight>

Next, we need to install a very recent version of <code>olm</code>, which must be hand-compiled at the time of writing. It is probably best to perform the following steps as a regular user instead of root, but I couldn't be bothered creating a new user. Caveat emptor.
<syntaxhighlight lang="bash">
cd
git clone https://gitlab.matrix.org/matrix-org/olm.git
cd olm
cmake . -Bbuild
cd build
make
# if you dropped root, use `sudo make install' here instead
make install
</syntaxhighlight>

Since <code>olm</code> is installed in /usr/local, we'll need to update the library path. These steps should be executed as root again:
<syntaxhighlight lang="bash" line>
cat >>/etc/profile.d/librarypath.sh <<EOF
LD_LIBRARY_PATH="/usr/local/lib"
export LD_LIBRARY_PATH
EOF
. /etc/profile
. ~/.bashrc
echo $LD_LIBRARY_PATH
</syntaxhighlight>

The last command should output <code>/usr/local/lib</code>. If so, we are now ready to compile mautrix-whatsapp. The following steps may be executed as a regular user if you want. Clone the repo and compile:
<syntaxhighlight lang="bash" line>
cd
git clone https://github.com/tulir/mautrix-whatsapp.git
cd mautrix-whatsapp
./build.sh
# Only execute the following if you executed the above as a regular user
cd ..
sudo cp -r mautrix-whatsapp /root/mautrix-whatsapp
</syntaxhighlight>

Again as root, copy <code>/root/mautrix-whatsapp/example-config.yaml</code> to <code>/root/mautrix-whatsapp/config.yaml</code> and edit the latter.
* Under <code>homeserver</code>, set <code>address</code> to <code>http://localhost:8008</code> and <code>domain</code> to <code>localhost</code>.
* Under <code>appservice</code>, set <code>hostname</code> to <code>127.0.0.1</code>.
* Under <code>database</code> (in the <code>appservice</code> section), set <code>type</code> to <code>postgres</code> and <code>uri</code> to <code>postgres://synapse:<password>@localhost/synapse?sslmode=disable</code>, where <code><password></code> should be replaced with the PostgreSQL password you picked earlier.
* Under <code>bridge</code>, set <code>private_chat_portal_meta</code> to <code>true</code>.

The <code>permissions</code> block under <code>bridge</code> should be something like this:
<syntaxhighlight lang="yaml" line>
permissions:
"*": relaybot
"localhost": user
"@alice:localhost": admin
</syntaxhighlight>
Here <code>alice</code> should be replaced with the username you chose when issuing the <code>register_new_matrix_user</code> command in Step 1.

Finally, set <code>directory</code> under <code>logging</code> to something more suitable, like <code>/var/log/mautrix-whatsapp</code>.

Now generate the appservice registration file, copy it to the Synapse configuration directory, and change its ownership so Synapse can read it:
<syntaxhighlight lang="bash" line>
cd /root/mautrix-whatsapp
./mautrix-whatsapp -g
cp registration.yaml /etc/matrix-synapse/wa_registration.yaml
chown matrix-synapse /etc/matrix-synapse/wa_registration.yaml
</syntaxhighlight>

Edit <code>/etc/matrix-synapse/homeserver.yaml</code>. Find the line with <code>app_service_config_files</code> (which is commented out) and, below the comment, add
<syntaxhighlight lang="yaml" line>
app_service_config_files:
- "/etc/matrix-synapse/wa_registration.yaml"
</syntaxhighlight>

Now restart Synapse:
<syntaxhighlight lang="bash">
systemctl restart matrix-synapse.service
</syntaxhighlight>

It is now time to test mautrix-whatsapp. For testing purposes, start the bridge in the foreground:
<syntaxhighlight lang="bash">
/root/mautrix-whatsapp/mautrix-whatsapp
</syntaxhighlight>

Connect to your homeserver with Element-Desktop or Element-Android and start a direct chat with <code>@whatsappbot:localhost</code>. You should get a message saying the room has been set up as the bridge management/status room. Type <code>help</code> and send the message. If the bot replies, you're good; if not, check the logs, and check/adjust your configuration carefully and restart Synapse and mautrix-whatsapp.

If all is working, go back to the terminal where you started <code>/root/mautrix-whatsapp/mautrix-whatsapp</code> and terminate the process with Ctrl-C. Now create a new file <code>/etc/systemd/system/mautrix-whatsapp.service</code> and enter the following:
<syntaxhighlight lang="ini" line>
[Unit]
Description=WhatsApp to Matrix bridge
Wants=matrix-synapse.service

[Service]
Type=exec
Environment="LD_LIBRARY_PATH=/usr/local/lib"
WorkingDirectory=/root/mautrix-whatsapp
ExecStart=/root/mautrix-whatsapp/mautrix-whatsapp
Restart=always
RestartSec=10
SyslogIdentifier=mautrix-whatsapp

[Install]
WantedBy=multi-user.target
</syntaxhighlight>

You should now be able to start mautrix-whatsapp using systemd:
<syntaxhighlight lang="bash" line>
systemctl start mautrix-whatsapp.service
systemctl enable mautrix-whatsapp.service
</syntaxhighlight>

Wait a few seconds for mautrix-whatsapp to finish loading, then message <code>help</code> to your bot again to make sure it still works. If it does, send it <code>login</code>, and use the actual (official) WhatsApp client to scan the WhatsApp Web QR code that the bot sends you. It should immediately start pulling a few chats, but most likely not your entire history. Ignore it for now. Open your Element client's settings, go to Help & Advanced, and find your access token. Copy it. Then send the bridge bot <code>login-matrix <access_token></code>, replacing <code><access_token></code> with the access token you just copied. This will enable double puppeting; see [https://github.com/tulir/mautrix-whatsapp/wiki/Authentication the Authentication guide].

If you are not content with the meagre amount of chats/messages pulled by the bot, go into each room it created and send <code>!wa delete-portal</code>. Then go back to your terminal/SSH session and edit <code>/root/mautrix-whatsapp/config.yaml</code> again. In the <code>bridge</code> section, edit these settings:
* <code>initial_chat_sync_count</code> -- this is the amount of WhatsApp group portals that should be created. You probably want to set this to at least the number of WhatsApp groups you're in, including "one-on-one" groups for people you've direct-messaged. If unsure, just pick a number that's definitely larger than that.
* <code>initial_history_fill_count</code> -- this is the amount of old messages that will be fetched. If you have some very active or old rooms, you will need a very large number here. One caveat: mautrix-whatsapp can get a bit wonky if it's syncing a large amount of messages, and may need to be killed and restarted a few times for the process to complete. That means you should also be monitoring the sync process.
* <code>sync_max_chat_age</code> -- this is the age cutoff in seconds for synced messages. Set it to something like 2000000000 (two billion seconds, or roughly 63 years) to effectively disable the age cutoff.
* <code>initial_history_disable_notifications</code> -- this determines whether you get a "new message" notification for every synced old message. If you set <code>initial_history_fill_count</code> to a large number, do yourself a ''huge'' favour and set this to <code>true</code>.

Now restart mautrix-whatsapp:
<syntaxhighlight lang="bash">
systemctl restart mautrix-whatsapp.service
</syntaxhighlight>

Finally, send the bridge bot <code>sync --create-all</code>. It will now start to pull the chats you chose. Bear in mind that this can take a very long time. If you notice it stops making progress, restart mautrix-whatsapp and send <code>sync --create-all</code> again: it will continue at the point it was stopped.

You are now basically done, although you probably still have WhatsApp running on your phone. The next step will explain how to migrate it to a VM.

=Step 4: migrate WhatsApp proper to a VM=
I have not performed this step yet myself. However, [https://github.com/tulir/mautrix-whatsapp/wiki/Android-VM-Setup the official guide by '''Alistair Francis'''] should be easy enough to follow. I will update this guide when I've done this myself.

N.B. in my current setup, WhatsApp runs on a [https://lineageos.org/ LineageOS] phone, and its traffic is piped through the VPN.

=Step 5: optional extras=
Finally, there are a few things you can do to extend this setup.

==Redirect port 443 to OpenVPN==
Some public Wi-Fi networks only allow access to a very restricted set of ports so clients are limited to web-browsing and checking email. This annoying bit of shit-tier network administration is easily circumvented by piping your traffic through a VPN, which, of course, you just set up -- but you have to be able to connect to the VPN in the first place, and port 1194 (OpenVPN's default port) is practically guaranteed to be blocked by such networks. Luckily, the default HTTPS port, TCP 443, is practically guaranteed to NOT be blocked, so if your OpenVPN server is using TCP, you can just redirect traffic from 443 to 1194 and log in to your VPN on basically any network. ''N.B. switch your OpenVPN over to TCP if you want to do this but chose UDP earlier.''

A few commands are all that's needed:
<syntaxhighlight lang="bash" line>
iptables -A PREROUTING -i eth0 -p tcp -m tcp --dport 443 -j REDIRECT --to-ports 1194
iptables -I INPUT 1 -p tcp -m tcp --dport 443 -j ACCEPT
iptables-save >/etc/iptables/rules.v4
</syntaxhighlight>

You can now use <code>remote 123.123.123.123 443</code> in your client configuration files. Also be sure to add <code>redirect-gateway def1</code> on clients that connect to public Wi-Fi!

==Install element-web==
The official element-web implementation at app.element.io does not work with a private homeserver, but element-web ''will'' work if you install it on your homeserver. '''Note that the authors of element-web specifically recommend against running element-web on the same domain as the homeserver.''' However, as access is limited to the VPN, the risk should be limited as long as only trusted and experienced users are allowed access to the VPN in the first place.

Download the latest release (1.75-rc1 at the time of writing; replace the version as necessary in what follows, obviously) from [https://github.com/vector-im/element-web/releases], extract it, move it to the proper place, and create the config file:
<syntaxhighlight lang="bash" line>
wget https://github.com/vector-im/element-web/releases/download/v1.7.15-rc.1/element-v1.7.15-rc.1.tar.gz
tar -xvzf element-v1.7.15-rc.1.tar.gz
mv element-v1.7.15-rc.1 /var/www/element-web
cd /var/www/element-web
cp config.sample.json config.json
</syntaxhighlight>

Edit <code>config.json</code>. Set <code>"base_url"</code> to <code>"https://192.168.16.1:10443"</code> and <code>"server_name"</code> to <code>"localhost"</code> in the <code>"m.homeserver"</code> block near the top. In the root block, set <code>"disable_custom_urls"</code> to <code>true</code> and <code>"default_federate"</code> to <code>false</code>.

Since we've already set up Nginx, we can just tell it to serve element-web as well, and we can even reuse the certificate authority. Edit the configuration file you created earlier, <code>/etc/nginx/sites-available/synapse</code> and add the following block at the end:
<syntaxhighlight lang="nginx" line>
server {
listen 10444 ssl;
server_name localhost;

root /var/www/element-web;
index index.html;

ssl on;
ssl_certificate /etc/matrix-synapse/easy-rsa/pki/issued/element-web.crt;
ssl_certificate_key /etc/matrix-synapse/easy-rsa/pki/private/element-web.key;
ssl_client_certificate /etc/matrix-synapse/easy-rsa/pki/ca.crt;
ssl_crl /etc/matrix-synapse/easy-rsa/pki/crl.pem;
ssl_verify_client on;

access_log /var/log/nginx-element-web-access_log.log;
error_log /var/log/nginx-element-web-error_log.log;
}
</syntaxhighlight>

If you did not manage to get <code>ssl_verify_client</code> to work earlier, remove that line here too. Also, if you did not use port 443 for OpenVPN, you may use <code>listen 443 ssl;</code> instead of <code>listen 10444 ssl;</code> if you want (so you can just point your browser at https://192.168.16.1). Finally, add an iptables rule to allow connecting from within the VPN, and restart Nginx:
<syntaxhighlight lang="bash" line>
# Replace 10444 with 443 if necessary
iptables -I INPUT 1 -s 192.168.16.0/24 -i tun0 -p tcp -m tcp --dport 10444 -j ACCEPT
iptables-save >/etc/iptables/rules.v4
systemctl restart nginx.service
</syntaxhighlight>

==Block Facebook on clients==
On all clients (except the phone running WhatsApp, if you have not moved it to a VM on the server yet), you can now completely block all Facebook-owned IPs and still retain access to WhatsApp using your Matrix homeserver. While tedious to do by hand (considering Facebook's IP pool grows like an aggressive tumour), it is easily automated on Linux with a cron job and iptables.

First of all, create a new iptables chain that will be used for automated IP blocking, and add it to the front of your INPUT and OUTPUT chains:
<syntaxhighlight lang="bash" line>
iptables -N BLOCK
iptables -I INPUT 1 -j BLOCK
iptables -I OUTPUT 1 -j BLOCK
</syntaxhighlight>

Next, we will create a script that finds the list of IPs owned by Facebook and adds them to the BLOCK chain. N.B. this requires <code>whois</code>, which should be available in any package manager under that name, so install it first if necessary. Then create the file <code>/etc/cron.hourly/ipblock.sh</code> with the following contents:
<syntaxhighlight lang="bash" line>
#!/bin/bash
iptables=/sbin/iptables

$iptables -F BLOCK

asns="AS32934"
for asn in asns
do
ips="$(whois -h whois.radb.net -- -i origin -T route $asn | grep route: | awk '{print $2}')"
for i in $ips
do
$iptables -A BLOCK -d $i -j REJECT --reject-with icmp-host-unreachable
$iptables -A BLOCK -s $i -j REJECT --reject-with icmp-host-unreachable
done
done
</syntaxhighlight>

This script queries whois.radb.net to find all IPs registered under the [https://en.wikipedia.org/wiki/Autonomous_system_(Internet) autonomous system number] AS32934, which is Facebook. You may add other ASNs too if you want. Note that although the list "only" contains 200 entries or so (at the time of writing), they include mask bits in CIDR notation: this list in fact represents tens of thousands of IP addresses, all owned by Facebook.

Make sure to make the script executable, and run it once if you don't want to wait until the next hour for cron to do it.
<syntaxhighlight lang="bash" line>
chmod +x /etc/cron.hourly/ipblock.sh
/etc/cron.hourly/ipblock.sh
iptables-save >/etc/iptables/rules.v4
</syntaxhighlight>

==Honourable mention: Pi-hole==
This is an honourable mention because I will not describe the installation process here and it is not related to mautrix-whatsapp. Nevertheless, as following this guide leaves you with a perfectly usable VPN server, and people reading this are likely to be privacy-conscious, I feel it is worthwhile to link [https://pi-hole.net/ Pi-hole] here. Pi-hole is a very powerful ad-blocking framework acting at DNS level. Like Synapse, you can configure Pi-hole to only be accessible to clients inside your VPN (by allowing only connections from 192.168.16.0/24 on device tun0). On your VPN clients, you can set 192.168.16.1 as your primary DNS server, so all clients are protected from malicious ads when connected to the VPN.

==Honourable mention: Tor proxy==
Your VPS can also serve as a VPN-wide proxy that sends traffic through [https://www.torproject.org/ Tor]. [https://www.marcus-povey.co.uk/2016/03/24/using-tor-as-a-http-proxy/ '''Marcus Povey''' has created a guide on how to set up a Tor proxy with polipo.]

Considering Tor's abysmal transfer speed, you probably don't ''always'' want to redirect traffic over Tor. Most browsers support [https://en.wikipedia.org/wiki/Proxy_auto-config proxy auto-config] (PAC), which allows you to fine-tune which sites get piped through the proxy. For example, the following PAC uses the Tor proxy to handle [https://en.wikipedia.org/wiki/.onion .onion] domains:
<syntaxhighlight lang="javascript" line>
function FindProxyForURL (url, host)
{
if (shExpMatch (host, "*.onion"))
{
return "PROXY 192.168.16.1:8123"
}
return "DIRECT;"
}
</syntaxhighlight>

Much more advanced configurations are possible with proxy auto-config, e.g. redirecting all HTTP traffic but not HTTPS, whitelisting/blacklisting domains.

File:Mautrix-whatsapp-setup-pathified.svg

2020-12-12T09:50:54Z

Link: Link uploaded a new version of File:Mautrix-whatsapp-setup-pathified.svg

== Summary ==
Graphical representation of a possible mautrix-whatsapp setup in a VPN.

File:Mautrix-whatsapp-setup-pathified.svg

2020-12-11T17:50:15Z

Link: Graphical representation of a possible mautrix-whatsapp setup in a VPN.

== Summary ==
Graphical representation of a possible mautrix-whatsapp setup in a VPN.

Main Page

2017-01-04T08:57:29Z

Link:

Welcome to '''Penguin Development'''! We make [[w:free and open-source software|free and open-source software]] and [[w:Open-source hardware|hardware]].

See below for current releases. All software and hardware is licensed under the [https://gnu.org/licenses/gpl.html GPL] (version 3 or higher) unless otherwise stated.

=Software=
* [[AUTOMOME]] — the OTTish AUTOMEME clone
* [[Ising]] — Monte Carlo Ising model simulator
* [[stackermann]] — a stack-based [[w:Ackermann function|Ackermann function]] calculator

=Hardware=
* [[timelapse]] — time-lapse trigger for digital cameras

=Code snippets and how-tos=
* [[Animated 3D plotting with Blender]]

=Other=
* [[LineageOS builds|Unofficial LineageOS builds]]

LineageOS builds

2017-01-04T08:56:37Z

Link: Created page with "[http://lineageos.org/ LineageOS] is a gratis and mostly free-as-in-freedom mobile operating system based on Android. It is a fork of the now-discontinued CyanogenMod. Until t..."

[http://lineageos.org/ LineageOS] is a gratis and mostly free-as-in-freedom mobile operating system based on Android. It is a fork of the now-discontinued CyanogenMod. Until the automatic build infrastructure is back online, unofficial builds for devices [[User:Link|I]] own will be available here.

=Disclaimer=
All builds that are found here are UNOFFICIAL and UNSUPPORTED. If you wish to use them, you must do so AT YOUR OWN RISK. No instructions on flashing ROMs will be provided here; these can be found on the [https://web.archive.org/web/20161224215208/https://wiki.cyanogenmod.org/w/Main_Page archived CyanogenMod Wiki]. Penguin Development cannot be held accountable if you brick your system! You and you alone are responsible for the consequences of flashing a custom ROM on your device.

'''LineageOS is ''not'' a Penguin Development project.''' The builds available here are simply compiled versions of the source code from the [https://github.com/lineageos LineageOS github repository], without modifications (unless specified). The purpose of this page is simply to save you the trouble of setting up a 100GB dev environment and using hours of CPU time to compile the source. For help in using the ROMs, see e.g. the archived CyanogenMod Wiki or [https://www.xda-developers.com/ XDA-developers]. Report bugs to the LineageOS maintainers directly.

=Devices=
[http://proj.penguindevelopment.org/lineage/htc/m7 HTC One m7]

Main Page

2016-11-10T10:06:28Z

Link:

Welcome to '''Penguin Development'''! We make [[w:free and open-source software|free and open-source software]] and [[w:Open-source hardware|hardware]].

See below for current releases. All software and hardware is licensed under the [https://gnu.org/licenses/gpl.html GPL] (version 3 or higher) unless otherwise stated.

=Software=
* [[AUTOMOME]] — the OTTish AUTOMEME clone
* [[Ising]] — Monte Carlo Ising model simulator
* [[stackermann]] — a stack-based [[w:Ackermann function|Ackermann function]] calculator

=Hardware=
* [[timelapse]] — time-lapse trigger for digital cameras

=Code snippets and how-tos=
* [[Animated 3D plotting with Blender]]

Animated 3D plotting with Blender

2016-11-09T15:15:40Z

Link: /* Output video */

[https://www.blender.org/ Blender] is an extremely versatile 3D creation and animation suite. Since it is fully scriptable in [https://www.python.org/ Python], Blender may be used to generate '''animated 3-dimensional plots''' of data or mathematical functions. Below is an example of one way to generate such a plot.

=Important information=
The script below has been tested with Blender 2.78a for Linux. It should generally be compatible with other versions and operating systems. The script works with the pristine Blender startup file; heavily modified startup files may break certain assumptions.

To run the script, simply call <code>blender --python blenderplot-ani.py</code>

To create the plot in a different base file, instead use <code>blender basefile.blend --python blenderplot-ani.py</code>.
The order of arguments matters here.

'''Note that the animation data will not be saved with your .blend file!''' This means you must run the Python script on a pristine "background" .blend file each time you wish to examine the geometry or create a render. If the .blend file is saved, only the first frame will be captured.

=The script=
Code for <code>blenderplot-ani.py</code> follows.
<syntaxhighlight lang="python" line>
#!/bin/true
# vim: se fo=tcroq tw=78 :
# Simple animated 3D plot example using Blender ( https://www.blender.org/ ).
# Given the function f(k, x, t)=exp(ikx-iωt), plots Re(f) against x and k,
# with colour given by Im(f) and t being the time.
#
# For pedagogical purposes, this just computes f at each frame (twice: once
# for the vertex positions and once for their colours). This is horribly
# inefficient; it would be much better to generate a 3D array for f(x, k, t)
# once and slice this array for each frame -- however, this is left as an
# exercise to the reader.
#
# To run, call
# blender --python blenderplot-ani.py

import os.path

import numpy as np

import bpy

### Begin user settings
omega = 1
font = '/usr/share/fonts/cm-unicode/cmunti.ttf' # Must be a unicode font!
### End user settings

### Begin generic Blender rendering code
# Global object counter.
obj_ind = 10000

plot_id = None

line_material = bpy.data.materials.new('line')
line_material.diffuse_color = (0, 0, 0)
line_material.diffuse_shader = 'LAMBERT'
line_material.specular_color = (0, 0, 0)
line_material.specular_shader = 'COOKTORR'
line_material.use_shadows = False
line_material.use_cast_shadows = False
line_material.use_raytrace = True
line_material.ambient = 0

text_material = bpy.data.materials.new('text')
text_material.diffuse_color = (.15, .05, .035)
text_material.diffuse_shader = 'OREN_NAYAR'
text_material.diffuse_intensity = .9
text_material.roughness = 2
text_material.specular_color = (.6, .2, .1)
text_material.specular_shader = 'PHONG'
text_material.specular_hardness = 80
text_material.specular_intensity = .85
text_material.use_shadows = True
text_material.use_cast_shadows = False
text_material.use_raytrace = True
text_material.raytrace_mirror.use = True
text_material.mirror_color = (.7, .3, .15)
text_material.raytrace_mirror.reflect_factor = .3
text_material.emit = 0
text_material.ambient = 0

plot_material = bpy.data.materials.new('plot')
plot_material.specular_color = (.5, .5, .5)
plot_material.specular_shader = 'COOKTORR'
plot_material.specular_intensity = .2
plot_material.use_shadows = True
plot_material.use_transparent_shadows = True
plot_material.use_raytrace = True
plot_material.use_transparency = True
plot_material.transparency_method = 'RAYTRACE'
plot_material.alpha = .95
plot_material.specular_alpha = 1
plot_material.raytrace_transparency.depth = 5
plot_material.use_vertex_color_paint = True

text_font = bpy.data.fonts.load(os.path.abspath(os.path.expanduser(font)))

def heatmap(heat):
"""Heat map: given a "heat" between 0 and 1, return a tuple of RGB
values."""
r = np.max((2*heat-1., 0))
b = np.max((1.-2*heat, 0))
return (r, 1.-r-b, b)

def zheat(z, zmin, zmax, **kwargs):
"""Colour a vertex based on its z-height compared to the minimum and
maximum z-values that occur."""
return heatmap((z-zmin)/(zmax-zmin if zmin != zmax else 1))

def plot_function(x, y, func, auto_axes = True, xmarks=None,
ymarks = None, zmarks = None, labels = None, thickness = 0.025,
text_rot = None, colourfunc=zheat, zmin = None, zmax = None):
"""Plot the function (lambda) func of x and y. The resulting surface is
smooth-shaded. Vertices may be coloured according to colourfunc: this is a
function that accepts the following parameters and returns an RGB-tuple:
x, y, z, xmin, xmax, ymin, ymax, zmin, zmax"""
global obj_ind, plot_id

ids = {
'axes': [],
'axis_labels': [],
'xmarks': [],
'ymarks': [],
'zmarks': [],
'xlabels': [],
'ylabels': [],
'zlabels': []
}

if text_rot is None:
text_rot = np.array((0, 0, 0))

if plot_id is None:
obj_id = 'plot_{}'.format(obj_ind)
obj_ind += 1
# Generate all vertices in the plot at z = 0
verts = [(i, j, 0) for i in x for j in y]
faces = []
count = 0
# Build faces from the vertices
for i in range(len(y)*(len(x)-1)):
if count < len(y)-1:
faces.append((i, i+1, i+len(y)+1, i+len(y)))
count += 1
else:
count = 0

# Create a mesh and an object at the origin
mesh = bpy.data.meshes.new(obj_id)
obj = bpy.data.objects.new(obj_id, mesh)
obj.location = (0, 0, 0)
bpy.context.scene.objects.link(obj)
mesh.from_pydata(verts, [], faces)
mesh.update(calc_edges=True)

# Create a new vertex colour map
colours = obj.data.vertex_colors.new()

# Set material
obj.data.materials.append(plot_material)

# Smooth-shade polygons
for pol in obj.data.polygons:
pol.use_smooth = True
else:
obj = bpy.data.objects[plot_id]
colours = obj.data.vertex_colors.active

verts = obj.data.vertices

# Move vertices to their correct position
for v in verts:
v.co.z = func(v.co.x, v.co.y)
obj.data.update(calc_edges=True)

sv = sorted([(v.co.x, v.co.y, v.co.z) for v in verts], key=lambda q: q[2])

# Colour vertices
for pol in obj.data.polygons:
for idx in pol.loop_indices:
co = obj.data.vertices[obj.data.loops[idx].vertex_index].co
colours.data[idx].color = colourfunc(x=co.x, y=co.y, z=co.z,
xmin=np.min(x), xmax=np.max(x),
ymin=np.min(y), ymax=np.max(y),
zmin=sv[0][2], zmax=sv[-1][2])

if auto_axes and plot_id is None:
# Axes
ids['axes'].append(add_line(np.array((min(x), min(y), 0)),
np.array((max(x), min(y), 0)), thickness, False))
ids['axes'].append(add_line(np.array((max(x), min(y), 0)),
np.array((max(x), max(y), 0)), thickness, False))
ids['axes'].append(add_line(
np.array((min(x), min(y), sv[0][2] if zmin is None else zmin)),
np.array((min(x), min(y), sv[-1][2] if zmax is None else zmax)),
thickness, False))
# Axis marks
if xmarks is not None:
for pos, label in xmarks:
p = np.array((pos, min(y), 0))
ids['xmarks'].append(add_line(p,
p-np.array((0, 1.5*thickness, 0)), thickness, False))
if label is not None and len(label) > 0:
ids['xlabels'].append(add_text(
p-np.array((0, 7*thickness, 0)), label,
thickness, text_rot))
if ymarks is not None:
for pos, label in ymarks:
p = np.array((max(x), pos, 0))
ids['ymarks'].append(add_line(p,
p+np.array((1.5*thickness, 0, 0)), thickness, False))
if label is not None and len(label) > 0:
ids[ 'ylabels'].append(add_text(
p+np.array((7*thickness, 0, 0)), label,
thickness, text_rot))
if zmarks is not None:
for pos, label in zmarks:
p = np.array((min(x), min(y), pos))
ids['zmarks'].append(add_line(p,
p-np.array((1.5*thickness/np.sqrt(2),
1.5*thickness/np.sqrt(2), 0)), thickness, False))
if label is not None and len(label) > 0:
ids['zlabels'].append(add_text(
p-np.array((7*thickness, 7*thickness, 0))/np.sqrt(2),
label, thickness, text_rot))

# Axis labels
if labels is not None:
ids['axis_labels'].append(add_text(
np.array((max(x)+8*thickness, min(y), 0)),
labels[0], 2*thickness, text_rot))
ids['axis_labels'].append(add_text(
np.array((max(x), max(y)+8*thickness, 0)),
labels[1], 2*thickness, text_rot))
ids['axis_labels'].append(add_text(
np.array((min(x), min(y),
(sv[-1][2] if zmax is None else zmax) + 8*thickness)),
labels[2], 2*thickness, text_rot))

if plot_id is None:
plot_id = obj_id

ids['plot'] = plot_id

return ids

def add_text(r, text, size=0.025, rotation=None):
"""Add text at the position r. Size is a relative parameter; use
trial-and-error here."""
global obj_ind
obj_id = 'text_{}'.format(obj_ind)
obj_ind += 1
rot = [np.pi/2, 0, 0] if rotation is None else rotation.tolist()
bpy.ops.object.text_add(location=r.tolist(), rotation=rot)
obj = bpy.context.active_object
obj.name = obj_id
obj.data.name = obj_id
obj.data.body = text

# Set the font
obj.data.font = text_font

obj.data.offset_x = -2*size
obj.data.offset_y = -2*size
obj.data.shear = 0.0
obj.data.size = 8*size
obj.data.space_character = 1
obj.data.space_word = 4*size
obj.data.extrude = size/3

obj.data.materials.append(text_material)

return obj_id

def add_line(r1, r2, w=0.01, rel_w=True):
"""Add a "line" (cylinder) between the points r1 and r2. The width is
either w (if rel_w is False) or w*|r2-r1| (if rel_w is True)."""
global obj_ind
obj_id = 'line_{}'.format(obj_ind)
obj_ind += 1
rc = (r2+r1)/2 # Centroid
rr = r2-rc # Position of r2 relative to centroid
r = np.sqrt(np.sum(rr**2))
theta = np.arccos(rr[2]/r)
phi = np.arctan2(rr[1], rr[0])
bpy.ops.mesh.primitive_cylinder_add(vertices=16,
radius=.5*w*(r if rel_w else 1), depth=2*r,
location=rc.tolist(), rotation=(0, theta, phi))
obj = bpy.context.active_object
obj.name = obj_id
for pol in obj.data.polygons:
pol.use_smooth = True
obj.data.materials.append(line_material)

return obj_id
### End generic Blender rendering code

def frame_change(scene):
"""Update the plot for a given frame."""
frame = min(max(scene.frame_current, 0), n_frames - 1)
plot_function(x, k, funcgen(t[frame]), colourfunc=colgen(t[frame]))
# Update the t-indicator
bpy.data.objects[ttext_id].data.body = 't = {: >4.3f}'.format(t[frame])

if __name__ == '__main__':
# Set up x, y and t data
n_frames = 51
nx = 101
nk = 101
xscale = 1/2
kscale = 1/3
zscale = 2
x = np.linspace(0, 10, nx)*xscale
k = np.linspace(0, 4*np.pi, nk)*kscale
t = np.linspace(0, 10, n_frames)

# Function to plot
func = lambda x, k, t: np.exp(1j*(k*x-omega*t))*zscale
# Generator for plottable function f(x, k) at time t
funcgen = lambda t: lambda x, k: np.real(func(x, k, t))
# Colour generator
colgen = lambda t: lambda x, y, **kwargs: \
heatmap((np.imag(func(x, y, t))+1)/2)

# Absolute z range for axes
azmin = -1*zscale
azmax = 1*zscale

# Axis marks
xmarks = [(i*xscale, str(i)) for i in range(1, 11)]
kmarks = [(j*np.pi/2*kscale, '{}π/2'.format(j if j != 1 else '') \
if j % 2 == 1 else '{}π'.format(j // 2 if j != 2 else '')) \
for j in range(1, 9)]
zmarks = [(z/10*zscale, str(z/10)) for z in range(-10, 12, 2)]

# Hide the 吸牛 splash screen
bpy.context.user_preferences.view.show_splash = False

# Remove existing meshes
for item in bpy.context.scene.objects:
if item.type == 'MESH':
bpy.context.scene.objects.unlink(item)
for item in bpy.data.objects:
if item.type == 'MESH':
bpy.data.objects.remove(item)
for item in bpy.data.meshes:
bpy.data.meshes.remove(item)

# Set the camera position
bpy.data.objects['Camera'].location = (11, -6, 5.5)
bpy.data.objects['Camera'].rotation_euler = (1.1, 0, 0.8)

# Let all texts face the camera
rot = np.array(bpy.data.objects['Camera'].rotation_euler)

# Initial t=0 plot; this also sets up the axes.
print(plot_function(x, k, funcgen(0),
True, labels=('x', 'k', 'z'), text_rot=rot, xmarks=xmarks,
ymarks=kmarks, zmarks=zmarks, zmin=azmin, zmax=azmax,
colourfunc=colgen(0)))

# Text label indicating current time
ttext_id = add_text(np.array((5.6, -1.2, 0)), 't = {: >4.2f}'.format(0),
size=0.05, rotation=rot)

# Set min/max/current frame
bpy.data.scenes['Scene'].frame_start = 0
bpy.data.scenes['Scene'].frame_end = n_frames - 1
bpy.data.scenes['Scene'].frame_current = 0

# Add frame change handler. This is what makes the animation happen!
bpy.app.handlers.frame_change_pre.append(frame_change)

# Add some environment lighting
wld = bpy.data.worlds['World']
wld.light_settings.use_environment_light = True
wld.light_settings.environment_energy = .5

# Add a white backdrop plane
plane_material = bpy.data.materials.new('backdrop')
plane_material.diffuse_color = (1, 1, 1)
plane_material.use_shadeless = True
bpy.ops.mesh.primitive_plane_add(location=(0, 0, -5))
bpy.context.active_object.scale = (50, 50, 0)
bpy.context.active_object.data.materials.append(plane_material)
</syntaxhighlight>

=Output video=
<html5media height="270" width="480">File:Animated 3D plot.ogv</html5media>

[[File:Animated 3D plot.ogv]] / [http://www.penguindevelopment.org/images/8/88/Animated_3D_plot.ogv Animated_3D_plot.ogv]

Main Page

2016-11-09T14:53:12Z

Link:

Welcome to '''Penguin Development''', a (currently one-man) organisation developing [[w:free and open-source software|free and open-source software]] and [[w:Open-source hardware|hardware]].

See below for current releases. All software and hardware is licensed under the [https://gnu.org/licenses/gpl.html GPL] (version 3 or higher) unless otherwise stated.

=Software=
* [[AUTOMOME]] — the OTTish AUTOMEME clone
* [[Ising]] — Monte Carlo Ising model simulator
* [[stackermann]] — a stack-based [[w:Ackermann function|Ackermann function]] calculator

=Hardware=
* [[timelapse]] — time-lapse trigger for digital cameras

=Code snippets and how-tos=
* [[Animated 3D plotting with Blender]]

Animated 3D plotting with Blender

2016-11-09T14:52:48Z

Link: Change to first-level headers

Main Page

2016-11-09T14:51:25Z

Link:

Animated 3D plotting with Blender

2016-11-09T14:26:28Z

Link: Embed video with Html5mediator.

[https://www.blender.org/ Blender] is an extremely versatile 3D creation and animation suite. Since it is fully scriptable in [https://www.python.org/ Python], Blender may be used to generate '''animated 3-dimensional plots''' of data or mathematical functions. Below is an example of one way to generate such a plot.

== Important information ==
The script below has been tested with Blender 2.78a for Linux. It should generally be compatible with other versions and operating systems. The script works with the pristine Blender startup file; heavily modified startup files may break certain assumptions.

To run the script, simply call <code>blender --python blenderplot-ani.py</code>

To create the plot in a different base file, instead use <code>blender basefile.blend --python blenderplot-ani.py</code>.
The order of arguments matters here.

'''Note that the animation data will not be saved with your .blend file!''' This means you must run the Python script on a pristine "background" .blend file each time you wish to examine the geometry or create a render. If the .blend file is saved, only the first frame will be captured.

== The script ==
Code for <code>blenderplot-ani.py</code> follows.
<syntaxhighlight lang="python" line>
#!/bin/true
# vim: se fo=tcroq tw=78 :
# Simple animated 3D plot example using Blender ( https://www.blender.org/ ).
# Given the function f(k, x, t)=exp(ikx-iωt), plots Re(f) against x and k,
# with colour given by Im(f) and t being the time.
#
# For pedagogical purposes, this just computes f at each frame (twice: once
# for the vertex positions and once for their colours). This is horribly
# inefficient; it would be much better to generate a 3D array for f(x, k, t)
# once and slice this array for each frame -- however, this is left as an
# exercise to the reader.
#
# To run, call
# blender --python blenderplot-ani.py

import os.path

import numpy as np

import bpy

### Begin user settings
omega = 1
font = '/usr/share/fonts/cm-unicode/cmunti.ttf' # Must be a unicode font!
### End user settings

### Begin generic Blender rendering code
# Global object counter.
obj_ind = 10000

plot_id = None

line_material = bpy.data.materials.new('line')
line_material.diffuse_color = (0, 0, 0)
line_material.diffuse_shader = 'LAMBERT'
line_material.specular_color = (0, 0, 0)
line_material.specular_shader = 'COOKTORR'
line_material.use_shadows = False
line_material.use_cast_shadows = False
line_material.use_raytrace = True
line_material.ambient = 0

text_material = bpy.data.materials.new('text')
text_material.diffuse_color = (.15, .05, .035)
text_material.diffuse_shader = 'OREN_NAYAR'
text_material.diffuse_intensity = .9
text_material.roughness = 2
text_material.specular_color = (.6, .2, .1)
text_material.specular_shader = 'PHONG'
text_material.specular_hardness = 80
text_material.specular_intensity = .85
text_material.use_shadows = True
text_material.use_cast_shadows = False
text_material.use_raytrace = True
text_material.raytrace_mirror.use = True
text_material.mirror_color = (.7, .3, .15)
text_material.raytrace_mirror.reflect_factor = .3
text_material.emit = 0
text_material.ambient = 0

plot_material = bpy.data.materials.new('plot')
plot_material.specular_color = (.5, .5, .5)
plot_material.specular_shader = 'COOKTORR'
plot_material.specular_intensity = .2
plot_material.use_shadows = True
plot_material.use_transparent_shadows = True
plot_material.use_raytrace = True
plot_material.use_transparency = True
plot_material.transparency_method = 'RAYTRACE'
plot_material.alpha = .95
plot_material.specular_alpha = 1
plot_material.raytrace_transparency.depth = 5
plot_material.use_vertex_color_paint = True

text_font = bpy.data.fonts.load(os.path.abspath(os.path.expanduser(font)))

def heatmap(heat):
"""Heat map: given a "heat" between 0 and 1, return a tuple of RGB
values."""
r = np.max((2*heat-1., 0))
b = np.max((1.-2*heat, 0))
return (r, 1.-r-b, b)

def zheat(z, zmin, zmax, **kwargs):
"""Colour a vertex based on its z-height compared to the minimum and
maximum z-values that occur."""
return heatmap((z-zmin)/(zmax-zmin if zmin != zmax else 1))

def plot_function(x, y, func, auto_axes = True, xmarks=None,
ymarks = None, zmarks = None, labels = None, thickness = 0.025,
text_rot = None, colourfunc=zheat, zmin = None, zmax = None):
"""Plot the function (lambda) func of x and y. The resulting surface is
smooth-shaded. Vertices may be coloured according to colourfunc: this is a
function that accepts the following parameters and returns an RGB-tuple:
x, y, z, xmin, xmax, ymin, ymax, zmin, zmax"""
global obj_ind, plot_id

ids = {
'axes': [],
'axis_labels': [],
'xmarks': [],
'ymarks': [],
'zmarks': [],
'xlabels': [],
'ylabels': [],
'zlabels': []
}

if text_rot is None:
text_rot = np.array((0, 0, 0))

if plot_id is None:
obj_id = 'plot_{}'.format(obj_ind)
obj_ind += 1
# Generate all vertices in the plot at z = 0
verts = [(i, j, 0) for i in x for j in y]
faces = []
count = 0
# Build faces from the vertices
for i in range(len(y)*(len(x)-1)):
if count < len(y)-1:
faces.append((i, i+1, i+len(y)+1, i+len(y)))
count += 1
else:
count = 0

# Create a mesh and an object at the origin
mesh = bpy.data.meshes.new(obj_id)
obj = bpy.data.objects.new(obj_id, mesh)
obj.location = (0, 0, 0)
bpy.context.scene.objects.link(obj)
mesh.from_pydata(verts, [], faces)
mesh.update(calc_edges=True)

# Create a new vertex colour map
colours = obj.data.vertex_colors.new()

# Set material
obj.data.materials.append(plot_material)

# Smooth-shade polygons
for pol in obj.data.polygons:
pol.use_smooth = True
else:
obj = bpy.data.objects[plot_id]
colours = obj.data.vertex_colors.active

verts = obj.data.vertices

# Move vertices to their correct position
for v in verts:
v.co.z = func(v.co.x, v.co.y)
obj.data.update(calc_edges=True)

sv = sorted([(v.co.x, v.co.y, v.co.z) for v in verts], key=lambda q: q[2])

# Colour vertices
for pol in obj.data.polygons:
for idx in pol.loop_indices:
co = obj.data.vertices[obj.data.loops[idx].vertex_index].co
colours.data[idx].color = colourfunc(x=co.x, y=co.y, z=co.z,
xmin=np.min(x), xmax=np.max(x),
ymin=np.min(y), ymax=np.max(y),
zmin=sv[0][2], zmax=sv[-1][2])

if auto_axes and plot_id is None:
# Axes
ids['axes'].append(add_line(np.array((min(x), min(y), 0)),
np.array((max(x), min(y), 0)), thickness, False))
ids['axes'].append(add_line(np.array((max(x), min(y), 0)),
np.array((max(x), max(y), 0)), thickness, False))
ids['axes'].append(add_line(
np.array((min(x), min(y), sv[0][2] if zmin is None else zmin)),
np.array((min(x), min(y), sv[-1][2] if zmax is None else zmax)),
thickness, False))
# Axis marks
if xmarks is not None:
for pos, label in xmarks:
p = np.array((pos, min(y), 0))
ids['xmarks'].append(add_line(p,
p-np.array((0, 1.5*thickness, 0)), thickness, False))
if label is not None and len(label) > 0:
ids['xlabels'].append(add_text(
p-np.array((0, 7*thickness, 0)), label,
thickness, text_rot))
if ymarks is not None:
for pos, label in ymarks:
p = np.array((max(x), pos, 0))
ids['ymarks'].append(add_line(p,
p+np.array((1.5*thickness, 0, 0)), thickness, False))
if label is not None and len(label) > 0:
ids[ 'ylabels'].append(add_text(
p+np.array((7*thickness, 0, 0)), label,
thickness, text_rot))
if zmarks is not None:
for pos, label in zmarks:
p = np.array((min(x), min(y), pos))
ids['zmarks'].append(add_line(p,
p-np.array((1.5*thickness/np.sqrt(2),
1.5*thickness/np.sqrt(2), 0)), thickness, False))
if label is not None and len(label) > 0:
ids['zlabels'].append(add_text(
p-np.array((7*thickness, 7*thickness, 0))/np.sqrt(2),
label, thickness, text_rot))

# Axis labels
if labels is not None:
ids['axis_labels'].append(add_text(
np.array((max(x)+8*thickness, min(y), 0)),
labels[0], 2*thickness, text_rot))
ids['axis_labels'].append(add_text(
np.array((max(x), max(y)+8*thickness, 0)),
labels[1], 2*thickness, text_rot))
ids['axis_labels'].append(add_text(
np.array((min(x), min(y),
(sv[-1][2] if zmax is None else zmax) + 8*thickness)),
labels[2], 2*thickness, text_rot))

if plot_id is None:
plot_id = obj_id

ids['plot'] = plot_id

return ids

def add_text(r, text, size=0.025, rotation=None):
"""Add text at the position r. Size is a relative parameter; use
trial-and-error here."""
global obj_ind
obj_id = 'text_{}'.format(obj_ind)
obj_ind += 1
rot = [np.pi/2, 0, 0] if rotation is None else rotation.tolist()
bpy.ops.object.text_add(location=r.tolist(), rotation=rot)
obj = bpy.context.active_object
obj.name = obj_id
obj.data.name = obj_id
obj.data.body = text

# Set the font
obj.data.font = text_font

obj.data.offset_x = -2*size
obj.data.offset_y = -2*size
obj.data.shear = 0.0
obj.data.size = 8*size
obj.data.space_character = 1
obj.data.space_word = 4*size
obj.data.extrude = size/3

obj.data.materials.append(text_material)

return obj_id

def add_line(r1, r2, w=0.01, rel_w=True):
"""Add a "line" (cylinder) between the points r1 and r2. The width is
either w (if rel_w is False) or w*|r2-r1| (if rel_w is True)."""
global obj_ind
obj_id = 'line_{}'.format(obj_ind)
obj_ind += 1
rc = (r2+r1)/2 # Centroid
rr = r2-rc # Position of r2 relative to centroid
r = np.sqrt(np.sum(rr**2))
theta = np.arccos(rr[2]/r)
phi = np.arctan2(rr[1], rr[0])
bpy.ops.mesh.primitive_cylinder_add(vertices=16,
radius=.5*w*(r if rel_w else 1), depth=2*r,
location=rc.tolist(), rotation=(0, theta, phi))
obj = bpy.context.active_object
obj.name = obj_id
for pol in obj.data.polygons:
pol.use_smooth = True
obj.data.materials.append(line_material)

return obj_id
### End generic Blender rendering code

def frame_change(scene):
"""Update the plot for a given frame."""
frame = min(max(scene.frame_current, 0), n_frames - 1)
plot_function(x, k, funcgen(t[frame]), colourfunc=colgen(t[frame]))
# Update the t-indicator
bpy.data.objects[ttext_id].data.body = 't = {: >4.3f}'.format(t[frame])

if __name__ == '__main__':
# Set up x, y and t data
n_frames = 51
nx = 101
nk = 101
xscale = 1/2
kscale = 1/3
zscale = 2
x = np.linspace(0, 10, nx)*xscale
k = np.linspace(0, 4*np.pi, nk)*kscale
t = np.linspace(0, 10, n_frames)

# Function to plot
func = lambda x, k, t: np.exp(1j*(k*x-omega*t))*zscale
# Generator for plottable function f(x, k) at time t
funcgen = lambda t: lambda x, k: np.real(func(x, k, t))
# Colour generator
colgen = lambda t: lambda x, y, **kwargs: \
heatmap((np.imag(func(x, y, t))+1)/2)

# Absolute z range for axes
azmin = -1*zscale
azmax = 1*zscale

# Axis marks
xmarks = [(i*xscale, str(i)) for i in range(1, 11)]
kmarks = [(j*np.pi/2*kscale, '{}π/2'.format(j if j != 1 else '') \
if j % 2 == 1 else '{}π'.format(j // 2 if j != 2 else '')) \
for j in range(1, 9)]
zmarks = [(z/10*zscale, str(z/10)) for z in range(-10, 12, 2)]

# Hide the 吸牛 splash screen
bpy.context.user_preferences.view.show_splash = False

# Remove existing meshes
for item in bpy.context.scene.objects:
if item.type == 'MESH':
bpy.context.scene.objects.unlink(item)
for item in bpy.data.objects:
if item.type == 'MESH':
bpy.data.objects.remove(item)
for item in bpy.data.meshes:
bpy.data.meshes.remove(item)

# Set the camera position
bpy.data.objects['Camera'].location = (11, -6, 5.5)
bpy.data.objects['Camera'].rotation_euler = (1.1, 0, 0.8)

# Let all texts face the camera
rot = np.array(bpy.data.objects['Camera'].rotation_euler)

# Initial t=0 plot; this also sets up the axes.
print(plot_function(x, k, funcgen(0),
True, labels=('x', 'k', 'z'), text_rot=rot, xmarks=xmarks,
ymarks=kmarks, zmarks=zmarks, zmin=azmin, zmax=azmax,
colourfunc=colgen(0)))

# Text label indicating current time
ttext_id = add_text(np.array((5.6, -1.2, 0)), 't = {: >4.2f}'.format(0),
size=0.05, rotation=rot)

# Set min/max/current frame
bpy.data.scenes['Scene'].frame_start = 0
bpy.data.scenes['Scene'].frame_end = n_frames - 1
bpy.data.scenes['Scene'].frame_current = 0

# Add frame change handler. This is what makes the animation happen!
bpy.app.handlers.frame_change_pre.append(frame_change)

# Add some environment lighting
wld = bpy.data.worlds['World']
wld.light_settings.use_environment_light = True
wld.light_settings.environment_energy = .5

# Add a white backdrop plane
plane_material = bpy.data.materials.new('backdrop')
plane_material.diffuse_color = (1, 1, 1)
plane_material.use_shadeless = True
bpy.ops.mesh.primitive_plane_add(location=(0, 0, -5))
bpy.context.active_object.scale = (50, 50, 0)
bpy.context.active_object.data.materials.append(plane_material)
</syntaxhighlight>

== Output video ==
<html5media height="270" width="480">File:Animated 3D plot.ogv</html5media>

Animated 3D plotting with Blender

2016-11-09T14:08:55Z

Link: Created page with "[https://www.blender.org/ Blender] is an extremely versatile 3D creation and animation suite. Since it is fully scriptable in [https://www.python.org/ Python], Blender may be..."

[https://www.blender.org/ Blender] is an extremely versatile 3D creation and animation suite. Since it is fully scriptable in [https://www.python.org/ Python], Blender may be used to generate '''animated 3-dimensional plots''' of data or mathematical functions. Below is an example of one way to generate such a plot.

== Important information ==
The script below has been tested with Blender 2.78a for Linux. It should generally be compatible with other versions and operating systems. The script works with the pristine Blender startup file; heavily modified startup files may break certain assumptions.

To run the script, simply call <code>blender --python blenderplot-ani.py</code>

To create the plot in a different base file, instead use <code>blender basefile.blend --python blenderplot-ani.py</code>.
The order of arguments matters here.

'''Note that the animation data will not be saved with your .blend file!''' This means you must run the Python script on a pristine "background" .blend file each time you wish to examine the geometry or create a render. If the .blend file is saved, only the first frame will be captured.

== The script ==
Code for <code>blenderplot-ani.py</code> follows.
<syntaxhighlight lang="python" line>
#!/bin/true
# vim: se fo=tcroq tw=78 :
# Simple animated 3D plot example using Blender ( https://www.blender.org/ ).
# Given the function f(k, x, t)=exp(ikx-iωt), plots Re(f) against x and k,
# with colour given by Im(f) and t being the time.
#
# For pedagogical purposes, this just computes f at each frame (twice: once
# for the vertex positions and once for their colours). This is horribly
# inefficient; it would be much better to generate a 3D array for f(x, k, t)
# once and slice this array for each frame -- however, this is left as an
# exercise to the reader.
#
# To run, call
# blender --python blenderplot-ani.py

import os.path

import numpy as np

import bpy

### Begin user settings
omega = 1
font = '/usr/share/fonts/cm-unicode/cmunti.ttf' # Must be a unicode font!
### End user settings

### Begin generic Blender rendering code
# Global object counter.
obj_ind = 10000

plot_id = None

line_material = bpy.data.materials.new('line')
line_material.diffuse_color = (0, 0, 0)
line_material.diffuse_shader = 'LAMBERT'
line_material.specular_color = (0, 0, 0)
line_material.specular_shader = 'COOKTORR'
line_material.use_shadows = False
line_material.use_cast_shadows = False
line_material.use_raytrace = True
line_material.ambient = 0

text_material = bpy.data.materials.new('text')
text_material.diffuse_color = (.15, .05, .035)
text_material.diffuse_shader = 'OREN_NAYAR'
text_material.diffuse_intensity = .9
text_material.roughness = 2
text_material.specular_color = (.6, .2, .1)
text_material.specular_shader = 'PHONG'
text_material.specular_hardness = 80
text_material.specular_intensity = .85
text_material.use_shadows = True
text_material.use_cast_shadows = False
text_material.use_raytrace = True
text_material.raytrace_mirror.use = True
text_material.mirror_color = (.7, .3, .15)
text_material.raytrace_mirror.reflect_factor = .3
text_material.emit = 0
text_material.ambient = 0

plot_material = bpy.data.materials.new('plot')
plot_material.specular_color = (.5, .5, .5)
plot_material.specular_shader = 'COOKTORR'
plot_material.specular_intensity = .2
plot_material.use_shadows = True
plot_material.use_transparent_shadows = True
plot_material.use_raytrace = True
plot_material.use_transparency = True
plot_material.transparency_method = 'RAYTRACE'
plot_material.alpha = .95
plot_material.specular_alpha = 1
plot_material.raytrace_transparency.depth = 5
plot_material.use_vertex_color_paint = True

text_font = bpy.data.fonts.load(os.path.abspath(os.path.expanduser(font)))

def heatmap(heat):
"""Heat map: given a "heat" between 0 and 1, return a tuple of RGB
values."""
r = np.max((2*heat-1., 0))
b = np.max((1.-2*heat, 0))
return (r, 1.-r-b, b)

def zheat(z, zmin, zmax, **kwargs):
"""Colour a vertex based on its z-height compared to the minimum and
maximum z-values that occur."""
return heatmap((z-zmin)/(zmax-zmin if zmin != zmax else 1))

def plot_function(x, y, func, auto_axes = True, xmarks=None,
ymarks = None, zmarks = None, labels = None, thickness = 0.025,
text_rot = None, colourfunc=zheat, zmin = None, zmax = None):
"""Plot the function (lambda) func of x and y. The resulting surface is
smooth-shaded. Vertices may be coloured according to colourfunc: this is a
function that accepts the following parameters and returns an RGB-tuple:
x, y, z, xmin, xmax, ymin, ymax, zmin, zmax"""
global obj_ind, plot_id

ids = {
'axes': [],
'axis_labels': [],
'xmarks': [],
'ymarks': [],
'zmarks': [],
'xlabels': [],
'ylabels': [],
'zlabels': []
}

if text_rot is None:
text_rot = np.array((0, 0, 0))

if plot_id is None:
obj_id = 'plot_{}'.format(obj_ind)
obj_ind += 1
# Generate all vertices in the plot at z = 0
verts = [(i, j, 0) for i in x for j in y]
faces = []
count = 0
# Build faces from the vertices
for i in range(len(y)*(len(x)-1)):
if count < len(y)-1:
faces.append((i, i+1, i+len(y)+1, i+len(y)))
count += 1
else:
count = 0

# Create a mesh and an object at the origin
mesh = bpy.data.meshes.new(obj_id)
obj = bpy.data.objects.new(obj_id, mesh)
obj.location = (0, 0, 0)
bpy.context.scene.objects.link(obj)
mesh.from_pydata(verts, [], faces)
mesh.update(calc_edges=True)

# Create a new vertex colour map
colours = obj.data.vertex_colors.new()

# Set material
obj.data.materials.append(plot_material)

# Smooth-shade polygons
for pol in obj.data.polygons:
pol.use_smooth = True
else:
obj = bpy.data.objects[plot_id]
colours = obj.data.vertex_colors.active

verts = obj.data.vertices

# Move vertices to their correct position
for v in verts:
v.co.z = func(v.co.x, v.co.y)
obj.data.update(calc_edges=True)

sv = sorted([(v.co.x, v.co.y, v.co.z) for v in verts], key=lambda q: q[2])

# Colour vertices
for pol in obj.data.polygons:
for idx in pol.loop_indices:
co = obj.data.vertices[obj.data.loops[idx].vertex_index].co
colours.data[idx].color = colourfunc(x=co.x, y=co.y, z=co.z,
xmin=np.min(x), xmax=np.max(x),
ymin=np.min(y), ymax=np.max(y),
zmin=sv[0][2], zmax=sv[-1][2])

if auto_axes and plot_id is None:
# Axes
ids['axes'].append(add_line(np.array((min(x), min(y), 0)),
np.array((max(x), min(y), 0)), thickness, False))
ids['axes'].append(add_line(np.array((max(x), min(y), 0)),
np.array((max(x), max(y), 0)), thickness, False))
ids['axes'].append(add_line(
np.array((min(x), min(y), sv[0][2] if zmin is None else zmin)),
np.array((min(x), min(y), sv[-1][2] if zmax is None else zmax)),
thickness, False))
# Axis marks
if xmarks is not None:
for pos, label in xmarks:
p = np.array((pos, min(y), 0))
ids['xmarks'].append(add_line(p,
p-np.array((0, 1.5*thickness, 0)), thickness, False))
if label is not None and len(label) > 0:
ids['xlabels'].append(add_text(
p-np.array((0, 7*thickness, 0)), label,
thickness, text_rot))
if ymarks is not None:
for pos, label in ymarks:
p = np.array((max(x), pos, 0))
ids['ymarks'].append(add_line(p,
p+np.array((1.5*thickness, 0, 0)), thickness, False))
if label is not None and len(label) > 0:
ids[ 'ylabels'].append(add_text(
p+np.array((7*thickness, 0, 0)), label,
thickness, text_rot))
if zmarks is not None:
for pos, label in zmarks:
p = np.array((min(x), min(y), pos))
ids['zmarks'].append(add_line(p,
p-np.array((1.5*thickness/np.sqrt(2),
1.5*thickness/np.sqrt(2), 0)), thickness, False))
if label is not None and len(label) > 0:
ids['zlabels'].append(add_text(
p-np.array((7*thickness, 7*thickness, 0))/np.sqrt(2),
label, thickness, text_rot))

# Axis labels
if labels is not None:
ids['axis_labels'].append(add_text(
np.array((max(x)+8*thickness, min(y), 0)),
labels[0], 2*thickness, text_rot))
ids['axis_labels'].append(add_text(
np.array((max(x), max(y)+8*thickness, 0)),
labels[1], 2*thickness, text_rot))
ids['axis_labels'].append(add_text(
np.array((min(x), min(y),
(sv[-1][2] if zmax is None else zmax) + 8*thickness)),
labels[2], 2*thickness, text_rot))

if plot_id is None:
plot_id = obj_id

ids['plot'] = plot_id

return ids

def add_text(r, text, size=0.025, rotation=None):
"""Add text at the position r. Size is a relative parameter; use
trial-and-error here."""
global obj_ind
obj_id = 'text_{}'.format(obj_ind)
obj_ind += 1
rot = [np.pi/2, 0, 0] if rotation is None else rotation.tolist()
bpy.ops.object.text_add(location=r.tolist(), rotation=rot)
obj = bpy.context.active_object
obj.name = obj_id
obj.data.name = obj_id
obj.data.body = text

# Set the font
obj.data.font = text_font

obj.data.offset_x = -2*size
obj.data.offset_y = -2*size
obj.data.shear = 0.0
obj.data.size = 8*size
obj.data.space_character = 1
obj.data.space_word = 4*size
obj.data.extrude = size/3

obj.data.materials.append(text_material)

return obj_id

def add_line(r1, r2, w=0.01, rel_w=True):
"""Add a "line" (cylinder) between the points r1 and r2. The width is
either w (if rel_w is False) or w*|r2-r1| (if rel_w is True)."""
global obj_ind
obj_id = 'line_{}'.format(obj_ind)
obj_ind += 1
rc = (r2+r1)/2 # Centroid
rr = r2-rc # Position of r2 relative to centroid
r = np.sqrt(np.sum(rr**2))
theta = np.arccos(rr[2]/r)
phi = np.arctan2(rr[1], rr[0])
bpy.ops.mesh.primitive_cylinder_add(vertices=16,
radius=.5*w*(r if rel_w else 1), depth=2*r,
location=rc.tolist(), rotation=(0, theta, phi))
obj = bpy.context.active_object
obj.name = obj_id
for pol in obj.data.polygons:
pol.use_smooth = True
obj.data.materials.append(line_material)

return obj_id
### End generic Blender rendering code

def frame_change(scene):
"""Update the plot for a given frame."""
frame = min(max(scene.frame_current, 0), n_frames - 1)
plot_function(x, k, funcgen(t[frame]), colourfunc=colgen(t[frame]))
# Update the t-indicator
bpy.data.objects[ttext_id].data.body = 't = {: >4.3f}'.format(t[frame])

if __name__ == '__main__':
# Set up x, y and t data
n_frames = 51
nx = 101
nk = 101
xscale = 1/2
kscale = 1/3
zscale = 2
x = np.linspace(0, 10, nx)*xscale
k = np.linspace(0, 4*np.pi, nk)*kscale
t = np.linspace(0, 10, n_frames)

# Function to plot
func = lambda x, k, t: np.exp(1j*(k*x-omega*t))*zscale
# Generator for plottable function f(x, k) at time t
funcgen = lambda t: lambda x, k: np.real(func(x, k, t))
# Colour generator
colgen = lambda t: lambda x, y, **kwargs: \
heatmap((np.imag(func(x, y, t))+1)/2)

# Absolute z range for axes
azmin = -1*zscale
azmax = 1*zscale

# Axis marks
xmarks = [(i*xscale, str(i)) for i in range(1, 11)]
kmarks = [(j*np.pi/2*kscale, '{}π/2'.format(j if j != 1 else '') \
if j % 2 == 1 else '{}π'.format(j // 2 if j != 2 else '')) \
for j in range(1, 9)]
zmarks = [(z/10*zscale, str(z/10)) for z in range(-10, 12, 2)]

# Hide the 吸牛 splash screen
bpy.context.user_preferences.view.show_splash = False

# Remove existing meshes
for item in bpy.context.scene.objects:
if item.type == 'MESH':
bpy.context.scene.objects.unlink(item)
for item in bpy.data.objects:
if item.type == 'MESH':
bpy.data.objects.remove(item)
for item in bpy.data.meshes:
bpy.data.meshes.remove(item)

# Set the camera position
bpy.data.objects['Camera'].location = (11, -6, 5.5)
bpy.data.objects['Camera'].rotation_euler = (1.1, 0, 0.8)

# Let all texts face the camera
rot = np.array(bpy.data.objects['Camera'].rotation_euler)

# Initial t=0 plot; this also sets up the axes.
print(plot_function(x, k, funcgen(0),
True, labels=('x', 'k', 'z'), text_rot=rot, xmarks=xmarks,
ymarks=kmarks, zmarks=zmarks, zmin=azmin, zmax=azmax,
colourfunc=colgen(0)))

# Text label indicating current time
ttext_id = add_text(np.array((5.6, -1.2, 0)), 't = {: >4.2f}'.format(0),
size=0.05, rotation=rot)

# Set min/max/current frame
bpy.data.scenes['Scene'].frame_start = 0
bpy.data.scenes['Scene'].frame_end = n_frames - 1
bpy.data.scenes['Scene'].frame_current = 0

# Add frame change handler. This is what makes the animation happen!
bpy.app.handlers.frame_change_pre.append(frame_change)

# Add some environment lighting
wld = bpy.data.worlds['World']
wld.light_settings.use_environment_light = True
wld.light_settings.environment_energy = .5

# Add a white backdrop plane
plane_material = bpy.data.materials.new('backdrop')
plane_material.diffuse_color = (1, 1, 1)
plane_material.use_shadeless = True
bpy.ops.mesh.primitive_plane_add(location=(0, 0, -5))
bpy.context.active_object.scale = (50, 50, 0)
bpy.context.active_object.data.materials.append(plane_material)
</syntaxhighlight>

== Output video ==
[[File:Animated 3D plot.ogv]]

File:Animated 3D plot.ogv

2016-11-09T13:50:37Z

Link: Example of an animated 3D plot made with Blender. See Animated 3D plotting with Blender.

Example of an animated 3D plot made with Blender. See [[Animated 3D plotting with Blender]].

Main Page

2016-04-15T10:42:13Z

Link:

Main Page

2016-04-15T10:41:53Z

Link:

Welcome to '''Penguin Development''', a (currently one-man) organisation developing [[w:free and open-source software|free and open-source software]] and [[w:Open-source hardware|hardware]].

See below for current releases. All software and hardware is licensed under the [https://gnu.org/licenses/gpl.html GPL] (version 3 or higher) unless otherwise stated.

=Software=
* [[AUTOMOME]] — the OTTish AUTOMEME clone
* [[Ising]] — Monte-Carlo Ising model simulator
* [[stackermann]] — a stack-based [[w:Ackermann function|Ackermann function]] calculator

=Hardware=
* [[timelapse]] — time-lapse trigger for digital cameras

Ising

2016-04-15T10:41:03Z

Link: Created page with "'''Ising''' is a Monte Carlo Ising model simulator on a ''D''-cubic lattice of sides ''L'', using helical boundary conditions. ''D''..."

'''Ising''' is a [[w:Monte Carlo method|Monte Carlo]] [[w:Ising model|Ising model]] simulator on a ''D''-cubic lattice of sides ''L'', using helical boundary conditions. ''D'' and ''L'' are specified at compile-time. It is written in C++11.

==Dependencies==
* GNU getopt
* A recent version of GCC (tested 4.8.5)
* boost::filesystem (optional but highly recommended)

==Obtaining and installing Ising==
Ising can be obtained from http://proj.penguindevelopment.org/ising/. [http://proj.penguindevelopment.org/ising/ising-latest.tar.xz Direct link to the latest version.]

Ising is installed using the standard autotools procedure, whereby ''L'' may be set through the parameter ''GRIDSIZE'':<pre>./configure GRIDSIZE=100
make
make install
</pre>
This will build Ising in 1D, 2D, 3D and 4D.

Ising can be built on Windows using Cygwin, though the execution speed appears to be suboptimal.

==Using Ising==
See the included man-page for information on how to use Ising.

==Using Ising as an API==
Since Ising makes heavy use of C++ templates, the implementation is entirely contained within header files. This means that no further libraries are necessary. To use Ising as an API, simply<pre>
#include <ising/ising.h>
</pre>

==Bugs and feedback==
{{bugs and feedback}}

[[Category:Software]]

AUTOMOME

2015-02-25T22:12:53Z

Link:

'''AUTOMOME''' is a random [[w:Internet meme|internet meme]] generator based on [[w:Snowclone|snowclone]] templates. It is a black-box reimplementation and extension of [http://automeme.net/ AUTOMEME] (now defunct), based on the English dialect known as ''OTTish'', spoken in the [http://forums.xkcd.com/viewtopic.php?f=7&t=101043 xkcd forums thread of the Time comic], better known as the ''One True Thread'' or ''OTC''. The canonical web version is available at http://automome.penguindevelopment.org/.

=Dependencies=
* Python 3, tested versions 3.2.3 and 3.4.1
* Unicode-compatible system
* Apache web sever or compatible (hosted web version only)
* Modern graphical web browser (web client only)
* Qt 4 and PySide 1.2.x (qautomome only)

=Obtaining and installing AUTOMOME=
AUTOMOME can be obtained from http://proj.penguindevelopment.org/automome/. [http://proj.penguindevelopment.org/automome/automome-latest.tar.xz Direct link to the latest version.]

AUTOMOME is designed to run from its own directory; <code>cd</code>ing to the directory and calling <code>automome.py</code> directly should work. Likewise, the web version should work out of the box if the AUTOMOME directory is in a location served by Apache.

If a setup is desired where the dictionary files (<code>*.dict.txt</code>) are placed in a different directory from the script files, the <code>AUTOMOME_PATH</code> environment variable may be set to the path to the dictionary files. <code>automome-web.py</code> may be placed in a different directory from <code>automome.py</code>, so long as <code>automome.py</code> is in the module search path; see [https://docs.python.org/3/tutorial/modules.html#the-module-search-path].

The client-side web interface <code>automome.html</code> by default attempts to get its data from <code>automome-web.py</code> at the same base URL as <code>automome.html</code>: e.g. if you host a web version of AUTOMOME at http://example.com/molpy/grapevine/automome.html, it will try to fetch data from http://example.com/molpy/grapevine/automome-web.py. Likewise, it will try to locate <code>cuegan.svg</code> in the same directory.

=Using AUTOMOME=
There are several ways to use AUTOMOME: as of version 4.0, it can be used as a text-only command-line version (<code>automome.py</code>), on the web using a fancy AJAX interface that gives nice formatting (<code>automome.html</code>, and the canonical version at http://automome.penguindevelopment.org/), as a text-only web version (<code>automome-web.py</code>), or using the graphical '''qautomome''' (<code>qautomome.py</code>).

==Using the command-line version==
The plaintext command-line version can be used on any system with Python 3.x, and is perhaps the simplest way to use AUTOMOME. At present, it supports only two significant options: picking the categories and the number of memes displayed. <code>automome.py --help</code> should provide an adequate explanation:<pre>$ automome.py --help
Usage: automome.py [option] [num]
[option] may be one of the following:
-h, --help show this message and exit
-V, --version show version and exit
-c [cats], --categories=[cats] generate memes from the categories [cats]
(see below); the default is aom

[cats] may be any combination of the following letters:
a molpish memes from the original AUTOMEME (possibly OTTified)
o molpish other memes, i.e. non-AUTOMEME memes
m molpish meta-memes, i.e. memes originating in the OTT
A unmolpish AUTOMEME memes
O unmolpish other memes
t OTToMeme memes (xkcd memes by azule)

[num] is the number of memes to generate; if it is missing or invalid, it is
assumed to be 1.</pre>

As an example, the following code produces 10 memes from the "Molpish other" and "Meta-memes" categories:<pre>
automome.py -c om 10</pre>

==Using the web GUI==
The [http://automome.penguindevelopment.org/ web GUI] offers more advanced features, including formatted text and the ability to filter memes. A quick run-through of features:
===Main layout===
From the main layout, clicking the image of Cuegan produces a single meme. There is not much more to be said.

===Meme categories===
Clicking the ''Meme categories'' link allows you to change the categories of memes that will be displayed; the categories are the same as those used in the text-only version.

===Filter settings===
The ''Filter settings'' tab is slightly more complicated. First and foremost is the ''Filter expression'' box. This allows you to enter any [https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions JavaScript regular expression], and only memes matching that expression will be displayed. Keep in mind that the regular expression is case sensitive; almost all words are uppercase. The regular expression is applied to the text-only version of the meme, so italicised words will be surrounded by underscores, and so on. If you wish to match all memes, leave the box blank or enter <code>.*</code>.

The ''Lock meme'' checkbox allows you to lock the template of the current meme: if it is active, clicking the Cuegan image will only produce memes using the same template as the currently shown meme.

===Copyable formats===
The ''Copyable formats'' tab provides three easy-to-copy output styles: plaintext (the same as <code>automome.py</code> itself would produce), BBCode (used on most forums) and (X)HTML, which can be used on your own websites.

==Using the text-only web version==
The text-only web version is a lightweight wrapper around the command-line version. In fact, if it is at all possible, you should use the command-line version directly. Nevertheless, if you still wish to use the text-only web version, simply point a browser at automome-web.py, either at your site or [http://automome.penguindevelopment.org/automome-web.py the canonical version]. Categories can be passed using the <code>c=</code> GET-parameter, and the number of memes can be passed using the <code>n=</code> GET-parameter. The categories are the same as the ones used in the text-only version, and the number of memes is limited to at most 100 at a time.

As an example, http://automome.penguindevelopment.org/automome-web.py?n=10&c=om produces 10 memes from the "Molpish other" and "Meta-memes" categories.

=Using qautomome=
qautomome is essentially a stand-alone version of the web client; most of the web client's feature descriptions transfer directly to qautomome and therefore aren't listed separately in this section. One notable capability of qautomome is the export function: qautomome can export the full history of memes to a file (or it can generate a set amount of new memes to export); the currently supported formats are [[w:Comma-separated values|CSV]] (which has plaintext, BBCode and (X)HTML fields) and [[w:fortune (Unix)|fortune]]. You can find this feature in the Copy/export tab.

In qautomome, there is no separate back-button; you can instead right-click Cuegan to view the previous meme. Keyboard-based operation is also possible; use the space bar, enter key or right arrow key for the next meme and backspace or the left arrow key for the previous one. Holding shift inverts the function.

==Bugs and feedback==
{{bugs and feedback}}

[[Category:Software]]

Main Page

2015-02-16T21:02:52Z

Link: /* Software */

Welcome to '''Penguin Development''', a (currently one-man) organisation developing [[w:free and open-source software|free and open-source software]] and [[w:Open-source hardware|hardware]].

See below for current releases. All software and hardware is licensed under the [https://gnu.org/licenses/gpl.html GPL] (version 3 or higher) unless otherwise stated.

=Software=
* [[AUTOMOME]] — the OTTish AUTOMEME clone
* [[stackermann]] — a stack-based [[w:Ackermann function|Ackermann function]] calculator

=Hardware=
* [[timelapse]] — time-lapse trigger for digital cameras

AUTOMOME

2015-02-16T21:01:47Z

Link: Created page with "'''AUTOMOME''' is a random internet meme generator based on snowclone templates. It is a black-box reimplementation and extension of [http:..."

'''AUTOMOME''' is a random [[w:Internet meme|internet meme]] generator based on [[w:Snowclone|snowclone]] templates. It is a black-box reimplementation and extension of [http://automeme.net/ AUTOMEME] (now defunct), based on the English dialect known as ''OTTish'', spoken in the [http://forums.xkcd.com/viewtopic.php?f=7&t=101043 xkcd forums thread of the Time comic], better known as the ''One True Thread'' or ''OTC''. The canonical web version is available at http://automome.penguindevelopment.org/.

=Dependencies=
* Python 3, tested versions 3.2.3 and 3.4.1
* Unicode-compatible system
* Apache web sever or compatible (hosted web version only)
* Modern graphical web browser (web client only)

=Obtaining and installing AUTOMOME=
AUTOMOME can be obtained from http://proj.penguindevelopment.org/automome/. [http://proj.penguindevelopment.org/automome/automome-latest.tar.xz Direct link to the latest version.]

AUTOMOME is designed to run from its own directory; <code>cd</code>ing to the directory and calling <code>automome.py</code> directly should work. Likewise, the web version should work out of the box if the AUTOMOME directory is in a location served by Apache.

If a setup is desired where the dictionary files (<code>*.dict.txt</code>) are placed in a different directory from the script files, the <code>AUTOMOME_PATH</code> environment variable may be set to the path to the dictionary files. <code>automome-web.py</code> may be placed in a different directory from <code>automome.py</code>, so long as <code>automome.py</code> is in the module search path; see [https://docs.python.org/3/tutorial/modules.html#the-module-search-path].

The client-side web interface <code>automome.html</code> by default attempts to get its data from <code>automome-web.py</code> at the same base URL as <code>automome.html</code>: e.g. if you host a web version of AUTOMOME at http://example.com/molpy/grapevine/automome.html, it will try to fetch data from http://example.com/molpy/grapevine/automome-web.py. Likewise, it will try to locate <code>cuegan.svg</code> in the same directory.

=Using AUTOMOME=
There are several ways to use AUTOMOME: as of version 3.x, it can be used as a text-only command-line version (<code>automome.py</code>), on the web using a fancy AJAX interface that gives nice formatting (<code>automome.html</code>, and the canonical version at http://automome.penguindevelopment.org/), or as a text-only web version (<code>automome-web.py</code>).

==Using the command-line version==
The plaintext command-line version can be used on any system with Python 3.x, and is perhaps the simplest way to use AUTOMOME. At present, it supports only two significant options: picking the categories and the number of memes displayed. <code>automome.py --help</code> should provide an adequate explanation:<pre>$ automome.py --help
Usage: automome.py [option] [num]
[option] may be one of the following:
-h, --help show this message and exit
-V, --version show version and exit
-c [cats], --categories=[cats] generate memes from the categories [cats]
(see below); the default is aom

[cats] may be any combination of the following letters:
a molpish memes from the original AUTOMEME (possibly OTTified)
o molpish other memes, i.e. non-AUTOMEME memes
m molpish meta-memes, i.e. memes originating in the OTT
A unmolpish AUTOMEME memes
O unmolpish other memes
t OTToMeme memes (xkcd memes by azule)

[num] is the number of memes to generate; if it is missing or invalid, it is
assumed to be 1.</pre>

As an example, the following code produces 10 memes from the "Molpish other" and "Meta-memes" categories:<pre>
automome.py -c om 10</pre>

==Using the web GUI==
The [http://automome.penguindevelopment.org/ web GUI] offers more advanced features, including formatted text and the ability to filter memes. A quick run-through of features:
===Main layout===
From the main layout, clicking the image of Cuegan produces a single meme. There is not much more to be said.

===Meme categories===
Clicking the ''Meme categories'' link allows you to change the categories of memes that will be displayed; the categories are the same as those used in the text-only version.

===Filter settings===
The ''Filter settings'' tab is slightly more complicated. First and foremost is the ''Filter expression'' box. This allows you to enter any [https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions JavaScript regular expression], and only memes matching that expression will be displayed. Keep in mind that the regular expression is case sensitive; almost all words are uppercase. The regular expression is applied to the text-only version of the meme, so italicised words will be surrounded by underscores, and so on. If you wish to match all memes, leave the box blank or enter <code>.*</code>.

The ''Lock meme'' checkbox allows you to lock the template of the current meme: if it is active, clicking the Cuegan image will only produce memes using the same template as the currently shown meme.

===Copyable formats===
The ''Copyable formats'' tab provides three easy-to-copy output styles: plaintext (the same as <code>automome.py</code> itself would produce), BBCode (used on most forums) and (X)HTML, which can be used on your own websites.

==Using the text-only web version==
The text-only web version is a lightweight wrapper around the command-line version. In fact, if it is at all possible, you should use the command-line version directly. Nevertheless, if you still wish to use the text-only web version, simply point a browser at automome-web.py, either at your site or [http://automome.penguindevelopment.org/automome-web.py the canonical version]. Categories can be passed using the <code>c=</code> GET-parameter, and the number of memes can be passed using the <code>n=</code> GET-parameter. The categories are the same as the ones used in the text-only version, and the number of memes is limited to at most 100 at a time.

As an example, http://automome.penguindevelopment.org/automome-web.py?n=10&c=om produces 10 memes from the "Molpish other" and "Meta-memes" categories.

==Bugs and feedback==
{{bugs and feedback}}

[[Category:Software]]

Stackermann

2013-09-17T19:30:59Z

Link: /* Normal usage */

{{lowercase}}
'''stackermann''' is a program that calculates the [[w:Ackermann function|Ackermann function]]. It utilises [http://gmplib.org/ GMP] in conjunction with a simplistic stack data-type to calculate the enormous values efficiently.

=Dependencies=
* UNIX-like system (probably includes Cygwin; not tested, though.)
* ≥ gmp-4.0

Additionally, accurate computation timing requires librt; this is used by default and is present on just about any sane system.

=Obtaining stackermann=
stackermann is available as a source tarball at http://proj.penguindevelopment.org/stackermann/. [http://proj.penguindevelopment.org/stackermann/stackermann-latest.tar.gz Direct link to the latest version.]

Installation follows the usual configure/make/make install procedure.

=Quick overview=
==Normal usage==
Given ''m'' and ''n'', stackermann simply calculates the value and prints it to stdout:
<pre>$ stackermann 4 1
A(4, 1)=65533</pre>
Use the <tt>-t</tt> option to suppress the leading ''A(m, n)='':<pre>$ stackermann -t 4 1
65533</pre>
If ''n'' is not given, ''n=m'' is assumed:<pre>$ stackermann 3
A(3, 3)=61</pre>
The <tt>-s</tt> option may be used to additionally print computation statistics to stderr:<pre>$ stackermann -s 3
A(3, 3)=61
Processing time: 0.001 s.
8 stack ops; max stack size 4 (~72 bytes).</pre>

==Benchmark mode==
In benchmark mode (the <tt>-b</tt> option), stackermann does not print the calculated value at all; instead, it prints statistics on what it took to calculate it. The output produced is printed as a space-separated list of—respectively—total computation time in seconds, total number of stack pushes, maximum number of stack entries, and approximate maximum stack size in bytes.
<pre>$ stackermann -b 4 2
0.050 131103 65534 1048552</pre>

==Additional options==
For an up-to-date overview of all available options and features, see the manpage included in the source tarball.

=Limitations, bugs and feedback=
==Limitations==
To improve efficiency, stackermann does not allow the ''m''-parameter to be greater than 255. In reality, this is unlikely to pose a problem, since no current computer will have the memory or speed required to compute the values with high ''m''-parameters anyway. ''This is not a bug; do NOT report it as one!''

==Bugs and feedback==
{{bugs and feedback}}

[[Category:Software]]

Stackermann

2013-09-17T12:02:44Z

Link: Bah humbug.

{{lowercase}}
'''stackermann''' is a program that calculates the [[w:Ackermann function|Ackermann function]]. It utilises [http://gmplib.org/ GMP] in conjunction with a simplistic stack data-type to calculate the enormous values efficiently.

=Dependencies=
* UNIX-like system (probably includes Cygwin; not tested, though.)
* ≥ gmp-4.0

Additionally, accurate computation timing requires librt; this is used by default and is present on just about any sane system.

=Obtaining stackermann=
stackermann is available as a source tarball at http://proj.penguindevelopment.org/stackermann/. [http://proj.penguindevelopment.org/stackermann/stackermann-latest.tar.gz Direct link to the latest version.]

Installation follows the usual configure/make/make install procedure.

=Quick overview=
==Normal usage==
Given ''m'' and ''n'', stackermann simply calculates the value and prints it to stdout:
<pre>$ stackermann 4 1
A(4, 1)=65533</pre>
Use the <tt>-t</tt> option to suppress the leading ''A(m, n)='':<pre>$ stackermann -t 4 1
65533</pre>
If ''n'' is not given, ''n=m'' is assumed:<pre>$stackermann 3
A(3, 3)=61</pre>
The <tt>-s</tt> option may be used to additionally print computation statistics to stderr:<pre>$ stackermann -s 3
A(3, 3)=61
Processing time: 0.001 s.
8 stack ops; max stack size 4 (~72 bytes).</pre>

==Benchmark mode==
In benchmark mode (the <tt>-b</tt> option), stackermann does not print the calculated value at all; instead, it prints statistics on what it took to calculate it. The output produced is printed as a space-separated list of—respectively—total computation time in seconds, total number of stack pushes, maximum number of stack entries, and approximate maximum stack size in bytes.
<pre>$ stackermann -b 4 2
0.050 131103 65534 1048552</pre>

==Additional options==
For an up-to-date overview of all available options and features, see the manpage included in the source tarball.

=Limitations, bugs and feedback=
==Limitations==
To improve efficiency, stackermann does not allow the ''m''-parameter to be greater than 255. In reality, this is unlikely to pose a problem, since no current computer will have the memory or speed required to compute the values with high ''m''-parameters anyway. ''This is not a bug; do NOT report it as one!''

==Bugs and feedback==
{{bugs and feedback}}

[[Category:Software]]

Stackermann

2013-09-17T12:02:05Z

Link: /* Normal usage */

{{lowercase}}
'''stackermann''' is a program that calculates the [[w:Ackermann function|Ackermann function]]. It utilises [http://gmplib.org/ GMP] in conjunction with a simplistic stack data-type to calculate the enormous values efficiently.

=Dependencies=
* UNIX-like system (probably includes Cygwin; not tested, though.)
* ≥ gmp-4.0

Additionally, accurate computation timing requires librt; this is used by default and is present on just about any sane system.

=Obtaining stackermann=
stackermann is available as a source tarball at http://proj.penguindevelopment.org/stackermann/. [http://proj.penguindevelopment.org/stackermann/stackermann-latest.tar.gz Direct link to the latest version.]

Installation follows the usual configure/make/make install procedure.

=Quick overview=
==Normal usage==
Given ''m'' and ''n'', stackermann simply calculates the value and prints it to stdout:
<pre>$ stackermann -t 4 1
A(4, 1)=65533</pre>
Use the <tt>-t</tt> option to suppress the leading ''A(m, n)='':<pre>$ stackermann 4 1
65533</pre>
If ''n'' is not given, ''n=m'' is assumed:<pre>$stackermann 3
A(3, 3)=61</pre>
The <tt>-s</tt> option may be used to additionally print computation statistics to stderr:<pre>$ stackermann -s 3
A(3, 3)=61
Processing time: 0.001 s.
8 stack ops; max stack size 4 (~72 bytes).</pre>

==Benchmark mode==
In benchmark mode (the <tt>-b</tt> option), stackermann does not print the calculated value at all; instead, it prints statistics on what it took to calculate it. The output produced is printed as a space-separated list of—respectively—total computation time in seconds, total number of stack pushes, maximum number of stack entries, and approximate maximum stack size in bytes.
<pre>$ stackermann -b 4 2
0.050 131103 65534 1048552</pre>

==Additional options==
For an up-to-date overview of all available options and features, see the manpage included in the source tarball.

=Limitations, bugs and feedback=
==Limitations==
To improve efficiency, stackermann does not allow the ''m''-parameter to be greater than 255. In reality, this is unlikely to pose a problem, since no current computer will have the memory or speed required to compute the values with high ''m''-parameters anyway. ''This is not a bug; do NOT report it as one!''

==Bugs and feedback==
{{bugs and feedback}}

[[Category:Software]]

Timelapse

2013-08-18T16:24:16Z

Link: /* Pictures */

{{lowercase}}
'''timelapse''' is a user-configurable automatic [[w:Time-lapse photography|time-lapse]] trigger for digital cameras; it allows taking photos at regular intervals without requiring user intervention. timelapse is based on the [http://www.atmel.com/devices/ATTINY2313.aspx ATtiny2313] microcontroller and provides a user-configurable timer with a resolution of 1 millisecond. It was designed with Canon EOS DSLR cameras in mind, but may well work with other brands.

timelapse was designed so that it may be built at home by electronics hobbyists.

=Features=
* Configurable delay of up to 999999.999 seconds (~11.57 days) with 1 ms resolution
* Configurable pulse width (with the same parameters as the delay) allowing timed exposure
* Configurable shot count; 1-10000 or infinite
* Fully digital configuration with LCD
* User settings stored in ROM
* Powered from 9 V battery

=Obtaining timelapse=
At present, the only way to obtain timelapse is to build and flash it yourself. The current (v0.1) board is a rough prototype that nonetheless does the job. A redesign of the PCB is planned; this should make it suitable to integrate into a case.

A tarball containing the design schematics, PCB layout, firmware sources and firmware HEX is available at http://proj.penguindevelopment.org/timelapse/. [http://proj.penguindevelopment.org/timelapse/timelapse-latest.tar.gz (Direct link to latest version.)] The schematic is in [http://wiki.geda-project.org/geda:gaf gEDA/gaf] .sch format, and the PCB layout is in [http://pcb.geda-project.org/ gEDA PCB] .pcb format.

For instructions on building the timelapse PCB, see the [[/README/]]. For instructions on flashing the firmware (and optionally compiling it yourself), see [[/INSTALL/]] (both files are also included in the tarball). [[/Parts list|A list of components is also available.]] For instruction on DIY PCB fabbing, use your favourite search engine. ;) (If you have a laser printer, you can try the toner transfer method, which was used to build the first prototype; [http://www.dr-lex.be/hardware/tonertransfer.html][http://www.riccibitti.com/pcb/pcb.htm].)

Keep in mind that you need an AVR programmer to flash the firmware. The [http://learn.adafruit.com/usbtinyisp USBTinyISP by Adafruit industries] is cheap and does the job.

=User guide=
Operating timelapse is fairly straight-forward. A quick guide can be found in the [[/README/]].

=Bugs and feedback=
{{bugs and feedback}}

=Pictures=
[[File:Timelapse startup.jpg|left|baseline|thumb|300px|Prototype showing the startup screen.]]
<br clear="all" />
For more pictures, see [http://users.penguindevelopment.org/Link/gallery2/v/electronics/ my personal gallery].

[[Category:Hardware]]