initial commit (release imminent)

LICENSE

@@ -0,0 +1,199 @@
+CERN Open Hardware Licence Version 2 - Permissive
+
+
+Preamble
+
+CERN has developed this licence to promote collaboration among
+hardware designers and to provide a legal tool which supports the
+freedom to use, study, modify, share and distribute hardware designs
+and products based on those designs. Version 2 of the CERN Open
+Hardware Licence comes in three variants: this licence, CERN-OHL-P
+(permissive); and two reciprocal licences: CERN-OHL-W (weakly
+reciprocal) and CERN-OHL-S (strongly reciprocal).
+
+The CERN-OHL-P is copyright CERN 2020. Anyone is welcome to use it, in
+unmodified form only.
+
+Use of this Licence does not imply any endorsement by CERN of any
+Licensor or their designs nor does it imply any involvement by CERN in
+their development.
+
+
+1 Definitions
+
+  1.1 'Licence' means this CERN-OHL-P.
+
+  1.2 'Source' means information such as design materials or digital
+      code which can be applied to Make or test a Product or to
+      prepare a Product for use, Conveyance or sale, regardless of its
+      medium or how it is expressed. It may include Notices.
+
+  1.3 'Covered Source' means Source that is explicitly made available
+      under this Licence.
+
+  1.4 'Product' means any device, component, work or physical object,
+      whether in finished or intermediate form, arising from the use,
+      application or processing of Covered Source.
+
+  1.5 'Make' means to create or configure something, whether by
+      manufacture, assembly, compiling, loading or applying Covered
+      Source or another Product or otherwise.
+
+  1.6 'Notice' means copyright, acknowledgement and trademark notices,
+      references to the location of any Notices, modification notices
+      (subsection 3.3(b)) and all notices that refer to this Licence
+      and to the disclaimer of warranties that are included in the
+      Covered Source.
+
+  1.7 'Licensee' or 'You' means any person exercising rights under
+      this Licence.
+
+  1.8 'Licensor' means a person who creates Source or modifies Covered
+      Source and subsequently Conveys the resulting Covered Source
+      under the terms and conditions of this Licence. A person may be
+      a Licensee and a Licensor at the same time.
+
+  1.9 'Convey' means to communicate to the public or distribute.
+
+
+2 Applicability
+
+  2.1 This Licence governs the use, copying, modification, Conveying
+      of Covered Source and Products, and the Making of Products. By
+      exercising any right granted under this Licence, You irrevocably
+      accept these terms and conditions.
+
+  2.2 This Licence is granted by the Licensor directly to You, and
+      shall apply worldwide and without limitation in time.
+
+  2.3 You shall not attempt to restrict by contract or otherwise the
+      rights granted under this Licence to other Licensees.
+
+  2.4 This Licence is not intended to restrict fair use, fair dealing,
+      or any other similar right.
+
+
+3 Copying, Modifying and Conveying Covered Source
+
+  3.1 You may copy and Convey verbatim copies of Covered Source, in
+      any medium, provided You retain all Notices.
+
+  3.2 You may modify Covered Source, other than Notices.
+
+      You may only delete Notices if they are no longer applicable to
+      the corresponding Covered Source as modified by You and You may
+      add additional Notices applicable to Your modifications.
+
+  3.3 You may Convey modified Covered Source (with the effect that You
+      shall also become a Licensor) provided that You:
+
+       a) retain Notices as required in subsection 3.2; and
+
+       b) add a Notice to the modified Covered Source stating that You
+          have modified it, with the date and brief description of how
+          You have modified it.
+
+  3.4 You may Convey Covered Source or modified Covered Source under
+      licence terms which differ from the terms of this Licence
+      provided that You:
+
+       a) comply at all times with subsection 3.3; and
+
+       b) provide a copy of this Licence to anyone to whom You
+          Convey Covered Source or modified Covered Source.
+
+
+4 Making and Conveying Products
+
+You may Make Products, and/or Convey them, provided that You ensure
+that the recipient of the Product has access to any Notices applicable
+to the Product.
+
+
+5 DISCLAIMER AND LIABILITY
+
+  5.1 DISCLAIMER OF WARRANTY -- The Covered Source and any Products
+      are provided 'as is' and any express or implied warranties,
+      including, but not limited to, implied warranties of
+      merchantability, of satisfactory quality, non-infringement of
+      third party rights, and fitness for a particular purpose or use
+      are disclaimed in respect of any Source or Product to the
+      maximum extent permitted by law. The Licensor makes no
+      representation that any Source or Product does not or will not
+      infringe any patent, copyright, trade secret or other
+      proprietary right. The entire risk as to the use, quality, and
+      performance of any Source or Product shall be with You and not
+      the Licensor. This disclaimer of warranty is an essential part
+      of this Licence and a condition for the grant of any rights
+      granted under this Licence.
+
+  5.2 EXCLUSION AND LIMITATION OF LIABILITY -- The Licensor shall, to
+      the maximum extent permitted by law, have no liability for
+      direct, indirect, special, incidental, consequential, exemplary,
+      punitive or other damages of any character including, without
+      limitation, procurement of substitute goods or services, loss of
+      use, data or profits, or business interruption, however caused
+      and on any theory of contract, warranty, tort (including
+      negligence), product liability or otherwise, arising in any way
+      in relation to the Covered Source, modified Covered Source
+      and/or the Making or Conveyance of a Product, even if advised of
+      the possibility of such damages, and You shall hold the
+      Licensor(s) free and harmless from any liability, costs,
+      damages, fees and expenses, including claims by third parties,
+      in relation to such use.
+
+
+6 Patents
+
+  6.1 Subject to the terms and conditions of this Licence, each
+      Licensor hereby grants to You a perpetual, worldwide,
+      non-exclusive, no-charge, royalty-free, irrevocable (except as
+      stated in this section 6, or where terminated by the Licensor
+      for cause) patent licence to Make, have Made, use, offer to
+      sell, sell, import, and otherwise transfer the Covered Source
+      and Products, where such licence applies only to those patent
+      claims licensable by such Licensor that are necessarily
+      infringed by exercising rights under the Covered Source as
+      Conveyed by that Licensor.
+
+  6.2 If You institute patent litigation against any entity (including
+      a cross-claim or counterclaim in a lawsuit) alleging that the
+      Covered Source or a Product constitutes direct or contributory
+      patent infringement, or You seek any declaration that a patent
+      licensed to You under this Licence is invalid or unenforceable
+      then any rights granted to You under this Licence shall
+      terminate as of the date such process is initiated.
+
+
+7 General
+
+  7.1 If any provisions of this Licence are or subsequently become
+      invalid or unenforceable for any reason, the remaining
+      provisions shall remain effective.
+
+  7.2 You shall not use any of the name (including acronyms and
+      abbreviations), image, or logo by which the Licensor or CERN is
+      known, except where needed to comply with section 3, or where
+      the use is otherwise allowed by law. Any such permitted use
+      shall be factual and shall not be made so as to suggest any kind
+      of endorsement or implication of involvement by the Licensor or
+      its personnel.
+
+  7.3 CERN may publish updated versions and variants of this Licence
+      which it considers to be in the spirit of this version, but may
+      differ in detail to address new problems or concerns. New
+      versions will be published with a unique version number and a
+      variant identifier specifying the variant. If the Licensor has
+      specified that a given variant applies to the Covered Source
+      without specifying a version, You may treat that Covered Source
+      as being released under any version of the CERN-OHL with that
+      variant. If no variant is specified, the Covered Source shall be
+      treated as being released under CERN-OHL-S. The Licensor may
+      also specify that the Covered Source is subject to a specific
+      version of the CERN-OHL or any later version in which case You
+      may apply this or any later version of CERN-OHL with the same
+      variant identifier published by CERN.
+
+  7.4 This Licence shall not be enforceable except by a Licensor
+      acting as such, and third party beneficiary rights are
+      specifically excluded.

README.md

@@ -0,0 +1,82 @@
+# ferric
+
+![a photo of the ferric keyboard on a wooden computer desk, surrounded with other small electronics.](images/lp_mx_01.jpeg)
+
+## Introduction
+
+ferric is a handwired split keyboard derived from the Sweep and Ferris. It is fully 3D-printable and features MCU hotswap without a PCB.
+
+## Features Over the Sweep
+
+- Tray, plate, and retainers are designed for 3D printing and fit together with only M2 screws
+- Retained header pins allow hotswapping a Pro Micro-style MCU without a PCB
+- Thumb clusters are angled "lower"
+
+*This initial release is for low-profile MX-spaced switches such as the Kailh Choc V2 and Gateron KS-33 series. Choc V1s can be used but this release is not designed for their spacing.*
+
+## Why?
+
+I disliked having to wait for a PCB, and wanted to try handwiring. I also wanted to be able to experiment with different MCUs or replace it if it breaks. As far as I have seen, there has been limited success found in implement hotswappable MCUs (in other boards) without a PCB, and most builds end up keeping the MCU floating and using a daughterboard, so I decided to try my hand at an implementation.
+
+## PCB-Less MCU Hotswap
+
+Female header pins are held in on one side by a small lip in the tray geometry, and on the other side by a removable retainer, which allows for simple yet durable installation. The only needed preparation is cutting the header pin body to size, and soldering the pins to the matrix. The space underneath the header pins can accommodate wires as large as 24 AWG, typically found inside Ethernet cables.
+
+## Build Guide
+
+### 0. BOM
+
+- 34x switches
+- 34x keycaps
+- 20x M2x4mm screws (flat head preferred)
+- 5x ["Shroomies" silicone feet](https://keeb.io/products/shroomies-silicone-feet) (optional, you can use whatever rubber feet you like)
+- 4 rows of header pins
+- 2 Pro Micro-style MCUs
+- 2 TRRS ports
+- 1 TRRS (or TRS) cable
+- 24-28 AWG insulated copper wire
+
+### 1. Printing
+
+The project comes with a 3mf file, ready to be opened in any slicer. **RH Tray** and **RH Plate** must be mirrored, and **Header Cap** must be printed twice.
+
+TODO: print settings, recommended printing procedure
+
+### 2. Switch Matrix
+
+Insert the switches so that their pins face south. Solder them into a matrix using your preferred handwiring method.
+
+TODO: place soldering photo
+
+Plan the routes of each of the cables that will connect the matrix to the headers, and leave about 2cm before cutting. There is limited space inside of the plate so it is recommended that you also straighten them out.
+
+### 3. TRRS Port
+
+Solder each wire as close to the port as possible, and sideways so that it leads behind the port. Flux and leaded solder will be your best friends to prevent the body from heating up too much before the joint is solid. Cut off the excess and lay the three wires flat on the body of the connector. Route them to their respective spaces under the MCU, but this time leave about 1cm before cutting.
+
+TODO: instructions for shorting out the side indicator pins
+
+### 4. Header Pins
+
+Count 17 pins from the end of a large header pin set, and pull out the first and last. Cut after them, as close to the next "outside" pin as possible. Sand or file the edges flat, only removing a tiny amount, then test-fit by inserting one edge on the north side of the space and pushing the other side in. Repeat until it is flush, do the same for the other side, and remove for soldering.
+
+Using a flat object or surface, bend each header pin 90 degrees. For every connection, remove a pin from the header body and solder it to its corresponding matrix connection. Soldering it this way keeps the body from melting and having a poor grip on the pin.
+
+### 5. Final Assembly
+
+Once everything is soldered, the TRRS port and header pins can be inserted. Then, place the switch plate in while tucking the matrix wires in as tight as possible. Gently screw on the header and TRRS caps and the switch plate with M2x4mm screws to prevent overthreading. Finally, install the keycaps.
+
+### 6. Flashing
+
+TODO: firmware and flashing instructions
+
+## Who Made This?
+
+- [**Pierre Chevalier**](https://github.com/pierrechevalier83), creator of the original [Ferris](https://github.com/pierrechevalier83/ferris)
+- [**David Barr**](https://github.com/davidphilipbarr), creator of the [Sweep](https://github.com/davidphilipbarr/Sweep)
+
+- [**skybldev** (monide)](https://skybldev.eu.org/), yours truly
+
+## License
+
+This project is licensed under [CERN OHL v2 Permissive](https://gitlab.com/ohwr/project/cernohl/-/wikis/Documents/CERN-OHL-version-2).