commit 07007efeab30900c61863d8939bf63b4dd207004 parent cad3fafcbd0b92676b3adcaeeeb05954ad7f57d7 Author: mntmn <lukas@mntmn.com> Date: Fri, 28 Sep 2018 16:59:38 +0200 added more handbook content Diffstat:
48 files changed, 1400 insertions(+), 33 deletions(-)
diff --git a/handbook/build/doctrees/TODO.doctree b/handbook/build/doctrees/TODO.doctree Binary files differ. diff --git a/handbook/build/doctrees/boot/index.doctree b/handbook/build/doctrees/boot/index.doctree Binary files differ. diff --git a/handbook/build/doctrees/case/index.doctree b/handbook/build/doctrees/case/index.doctree Binary files differ. diff --git a/handbook/build/doctrees/debug/index.doctree b/handbook/build/doctrees/debug/index.doctree Binary files differ. diff --git a/handbook/build/doctrees/environment.pickle b/handbook/build/doctrees/environment.pickle Binary files differ. diff --git a/handbook/build/doctrees/index.doctree b/handbook/build/doctrees/index.doctree Binary files differ. diff --git a/handbook/build/doctrees/keyboard/index.doctree b/handbook/build/doctrees/keyboard/index.doctree Binary files differ. diff --git a/handbook/build/doctrees/motherboard/attiny.doctree b/handbook/build/doctrees/motherboard/attiny.doctree Binary files differ. diff --git a/handbook/build/doctrees/motherboard/index.doctree b/handbook/build/doctrees/motherboard/index.doctree Binary files differ. diff --git a/handbook/build/doctrees/quickstart/index.doctree b/handbook/build/doctrees/quickstart/index.doctree Binary files differ. diff --git a/handbook/build/doctrees/thermal/index.doctree b/handbook/build/doctrees/thermal/index.doctree Binary files differ. diff --git a/handbook/build/doctrees/trackball/index.doctree b/handbook/build/doctrees/trackball/index.doctree Binary files differ. diff --git a/handbook/build/html/TODO.html b/handbook/build/html/TODO.html @@ -0,0 +1,127 @@ + +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta http-equiv="X-UA-Compatible" content="IE=Edge" /> + <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> + <title>topics todo — Reform documentation</title> + <link rel="stylesheet" href="_static/mntstyle.css" type="text/css" /> + <link rel="stylesheet" href="_static/pygments.css" type="text/css" /> + <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script> + <script type="text/javascript" src="_static/jquery.js"></script> + <script type="text/javascript" src="_static/underscore.js"></script> + <script type="text/javascript" src="_static/doctools.js"></script> + <link rel="index" title="Index" href="genindex.html" /> + <link rel="search" title="Search" href="search.html" /> + </head><body> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + accesskey="I">index</a></li> + <li class="nav-item nav-item-0"><a href="index.html">Reform documentation</a> »</li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body" role="main"> + + <div class="section" id="topics-todo"> +<h1>topics todo<a class="headerlink" href="#topics-todo" title="Permalink to this headline">¶</a></h1> +<p>faq +- how full/empty is the battery? +- how do i change the display brightness?</p> +<blockquote> +<div>brightnessctl s [1-7]</div></blockquote> +<ul> +<li><p class="first">what temperature does the cpu/system have?</p> +<p>cat /sys/class/thermal/thermal_zone0/temp</p> +</li> +<li><p class="first">how do i use the proprietary hardware video decoder?</p> +</li> +<li><p class="first">what does the boot rom do?</p> +</li> +<li><p class="first">where are the schematics for tinyRex?</p> +</li> +<li><p class="first">where are the schematics for REFORM?</p> +<p>The schematics of the motherboard, keyboard and trackball are in the git repository <a class="reference external" href="https://github.com/mntmn/reform">https://github.com/mntmn/reform</a></p> +</li> +<li><p class="first">how do i use an LTE modem/WWAN?</p> +<p>The only modem tested so far is Huawei XYZ999. It presents itself as 5 serial ports (tty*) and an ethernet device in the system. +You have to connect with a serial terminal like screen to /dev/tty* and issue AT commands to unlock the SIM and connect to the internet.</p> +</li> +<li><p class="first">how do i setup WiFi on the console?</p> +<p>wicd-curses</p> +</li> +<li><p class="first">can i use a discrete graphics card by nvidia or amd?</p> +</li> +<li><p class="first">what is the resolution of the display?</p> +</li> +</ul> +<p>The internal display has a resolution of 1366x768, but it is configured in the device tree (DTS) as 1368x768 to avoid problems with graphics drivers/hardware that can only handle multiples of 8 as the width.</p> +<ul class="simple"> +<li>what is the maximum resolution of HDMI?</li> +</ul> +<p>The maximum tested resolution of the HDMI output is 1920x1200.</p> +<ul class="simple"> +<li>how do i use the microphone input in the headphone jack?</li> +<li>where are the speakers?</li> +</ul> +<p>Reform does not include any speakers, but a stereo speaker module is in the making. You can also build your own by connecting an amplifier and speakers to the motherboard header labelled Line Out.</p> +<ul class="simple"> +<li>how do i use SPI, I2C, GPIO?</li> +<li>how do i use CSI, DSI?</li> +<li>how can i use the bootrom’s usb device mode?</li> +<li>how do i print/make my own case part?</li> +<li>how do i make a new keycap?</li> +<li>how to use OpenGL/ES hardware acceleration in Xorg?</li> +<li>how to use OpenGL/ES hardware acceleration in wayland?</li> +<li>software/game XYZ does not work, is there a workaround?</li> +<li>how can i run x86 software?</li> +<li>how can i run Raspberry Pi compatible software?</li> +</ul> +</div> + + + </div> + </div> + </div> + <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> + <div class="sphinxsidebarwrapper"> +<h3><a href="index.html">Table Of Contents</a></h3> +<ul> +<li class="toctree-l1"><a class="reference internal" href="quickstart/index.html">Quick Start</a></li> +<li class="toctree-l1"><a class="reference internal" href="case/index.html">The Case</a></li> +<li class="toctree-l1"><a class="reference internal" href="motherboard/index.html">The Motherboard</a></li> +<li class="toctree-l1"><a class="reference internal" href="motherboard/attiny.html">The ATTiny</a></li> +<li class="toctree-l1"><a class="reference internal" href="keyboard/index.html">The Keyboard</a></li> +<li class="toctree-l1"><a class="reference internal" href="trackball/index.html">The Trackball</a></li> +<li class="toctree-l1"><a class="reference internal" href="thermal/index.html">Thermal</a></li> +<li class="toctree-l1"><a class="reference internal" href="boot/index.html">System Boot Details</a></li> +<li class="toctree-l1"><a class="reference internal" href="debug/index.html">Debugging</a></li> +</ul> + + </div> + </div> + <div class="clearer"></div> + </div> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + >index</a></li> + <li class="nav-item nav-item-0"><a href="index.html">Reform documentation</a> »</li> + </ul> + </div> + <div class="footer" role="contentinfo"> + © Copyright 2018, Lukas F. Hartmann (mntmn). + Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.9. + </div> + </body> +</html> +\ No newline at end of file diff --git a/handbook/build/html/_sources/TODO.rst.txt b/handbook/build/html/_sources/TODO.rst.txt @@ -0,0 +1,55 @@ +topics todo +=========== + +faq +- how full/empty is the battery? +- how do i change the display brightness? + + brightnessctl s [1-7] + +- what temperature does the cpu/system have? + + cat /sys/class/thermal/thermal_zone0/temp + +- how do i use the proprietary hardware video decoder? + +- what does the boot rom do? +- where are the schematics for tinyRex? +- where are the schematics for REFORM? + + The schematics of the motherboard, keyboard and trackball are in the git repository https://github.com/mntmn/reform + +- how do i use an LTE modem/WWAN? + + The only modem tested so far is Huawei XYZ999. It presents itself as 5 serial ports (tty*) and an ethernet device in the system. + You have to connect with a serial terminal like screen to /dev/tty* and issue AT commands to unlock the SIM and connect to the internet. + +- how do i setup WiFi on the console? + + wicd-curses + +- can i use a discrete graphics card by nvidia or amd? +- what is the resolution of the display? + +The internal display has a resolution of 1366x768, but it is configured in the device tree (DTS) as 1368x768 to avoid problems with graphics drivers/hardware that can only handle multiples of 8 as the width. + +- what is the maximum resolution of HDMI? + +The maximum tested resolution of the HDMI output is 1920x1200. + +- how do i use the microphone input in the headphone jack? +- where are the speakers? + +Reform does not include any speakers, but a stereo speaker module is in the making. You can also build your own by connecting an amplifier and speakers to the motherboard header labelled Line Out. + +- how do i use SPI, I2C, GPIO? +- how do i use CSI, DSI? +- how can i use the bootrom's usb device mode? +- how do i print/make my own case part? +- how do i make a new keycap? +- how to use OpenGL/ES hardware acceleration in Xorg? +- how to use OpenGL/ES hardware acceleration in wayland? +- software/game XYZ does not work, is there a workaround? +- how can i run x86 software? +- how can i run Raspberry Pi compatible software? + diff --git a/handbook/build/html/_sources/boot/index.rst.txt b/handbook/build/html/_sources/boot/index.rst.txt @@ -6,7 +6,7 @@ Powering Up When the power switch is turned on, the TinyRex circuit receives power. If it is happy with the applied voltages (POWEROK signals are present), the green LED on the TinyRex module will light up. If only the red LED lights up, there is a problem with the power supply. -Next, the i.MX6 chip will jump to internal boot ROM code at memory address _0x00000000_. The boot ROM looks for an SD card on port SD1 and reads the DCD (Device Configuration Data) table from physical address 0x400 (1024 decimal, or the second physical block) on the SD card. This means that you can only use the MBR partition scheme on the boot disk, as it only occupies the first disk block. The more modern GPT partition format could work in theory, but most GPT tools and parsers do not understand GPT structures where the second block is in an alternative location. +Next, the i.MX6 chip will jump to internal boot ROM code at memory address *0x00000000*. The boot ROM looks for an SD card on port SD1 and reads the DCD (Device Configuration Data) table from physical address 0x400 (1024 decimal, or the second physical block) on the SD card. This means that you can only use the MBR partition scheme on the boot disk, as it only occupies the first disk block. The more modern GPT partition format could work in theory, but most GPT tools and parsers do not understand GPT structures where the second block is in an alternative location. We recommend to use the SD card as a boot and rescue disk, and set up an mSATA SSD disk with your actual operating system and data. You can then use alternative partition schemes and encryption. diff --git a/handbook/build/html/_sources/debug/index.rst.txt b/handbook/build/html/_sources/debug/index.rst.txt @@ -0,0 +1,42 @@ +Debugging +========= + +Power +----- + +The TinyRex module has a red and a green LED. Both have to light up to signal good power. + +To troubleshoot power, disconnect the internal battery and all internal and external peripherals, connect the 5V wall adapter. If you want to unplug the TinyRex module, you should take the motherboard out of the case first. + +Turn the power switch on. Get a multimeter and find the following voltages in the system: + +- **5V** The main input rail. Can be found on pin 1 of J25 or J29. +- **3.3V** The big regulator U4 (AP1501A-33) turns 5V into 3.3V. Check test point TP3 next to the big coil L2. +- **2.5V** Regulated by U11 (LP3962EMP-2.5). Check TP5 next to it. +- **1.5V** Regulated by U13. Check TP12. Needed for PCIe. +- **1.1V** Regulated by U5 near the USB hub U9. Check TP6. + +If voltages are way off, there can be a short somewhere on the board which usually generates heat. + +Serial Console +-------------- + +The motherboard connector labelled CONSOLE is a serial port (UART) to which U-Boot and the Linux kernel output diagnostic information on startup. The baud rate is 115200. + +Wire up a generic USB-to-UART adapter to the following pins of J25 (pin 1 is next to the J25 label): + +- **1** 5V, don't connect +- **2** UART1_TXD, connect to RX of your adapter +- **3** UART1_RXD, connect to TX of your adapter +- **4** UART1_RTS, don't connect +- **5** UART1_CTS, don't connect +- **6** GND, connect to GND of your adapter + +Then, use a terminal program such as screen on your host computer: + +.. code-block:: shell + + screen /dev/ttyUSB0 115200 + +If you then switch on Reform with a prepared SD card inserted, you should see the U-Boot console in *screen*. + diff --git a/handbook/build/html/_sources/index.rst.txt b/handbook/build/html/_sources/index.rst.txt @@ -17,4 +17,10 @@ Table of Contents quickstart/index case/index motherboard/index + motherboard/attiny + keyboard/index + trackball/index + thermal/index boot/index + debug/index + faq/index diff --git a/handbook/build/html/_sources/keyboard/index.rst.txt b/handbook/build/html/_sources/keyboard/index.rst.txt @@ -0,0 +1,48 @@ +The Keyboard +============ + +The keyboard is a row/column matrix scanner with anti-ghosting diodes on each switch. Each row and column is connected to one pin of the ATMega32U4_ 8-bit microcontroller. This microcontroller runs a firmware based on LUFA_. This converts the scanned out keycodes to the USB HID protocol. + +Firmware +-------- + +You can find the Reform keyboard firmware_ in the source folder "reform-keyboard-fw". + +To modify the scancodes of the keyboard matrix, edit the file Keyboard.c and rebuild the firmware by typing the following command in a terminal: + +.. code-block:: shell + + make + +To be able to flash the firmware to the keyboard, the ATMega has to be in a special mode where it identifies as an "Atmega DFU bootloader" USB device. This is achieved by shorting the pins HWB and GND with a jumper and then briefly shorting the RESET pin to ground. + +The RESET pin is pin 2 of J1, pin 1 is GND. + +HWB and GND are pins 3 and 4 of J3, respectively. Start counting at the "J3" label. + +The keyboard will reappear as a Atmel DFU bootloader USB device. You can then upload your new firmware by executing: + +.. code-block:: shell + + ./flash.sh + +Replacing a Keycap +------------------ + +The keycaps of the Reform beta units are printed with Clear Resin on Formlabs Form2 printers and then sanded by hand. Small irregularities are normal and a result of this process. The stems of the square 1x1 keycaps are slightly wider than the stems of other keycaps to make them more stable. This makes them harder to remove without breaking a stem. If a stem breaks inside of the keyswitch, you'll have to replace the keyswitch (see the following section). + +To pull out bigger keycaps, use pincers and try to push them between the top of the switch and the cap and wiggle very carefully and evenly until you can pull out the cap. + +There are some companies who produce "standard" Cherry ML keycaps, such as GMK_. + +Replacing a Keyswitch +--------------------- + +Only 2 of the 4 Cherry ML switch pins are soldered in to make it easier to swap switches with just a soldering iron. Set your iron/station to 380 degrees and dissolve the solder of one pin. Try to pull out the corresponding side of the switch from the top while continuing to heat the pin. Repeat the same for the other pin and go back and forth until you can remove the switch. + +Replace with model Cherry ML1A-11JW. + +.. _LUFA: http://www.fourwalledcubicle.com/files/LUFA/Doc/170418/html/ +.. _ATMega32U4: http://ww1.microchip.com/downloads/en/DeviceDoc/Atmel-7766-8-bit-AVR-ATmega16U4-32U4_Datasheet.pdf +.. _GMK: https://www.gmk-electronic-design.de/en.html +.. _firmware: https://github.com/mntmn/reform/reform-keyboard-fw diff --git a/handbook/build/html/_sources/motherboard/attiny.rst.txt b/handbook/build/html/_sources/motherboard/attiny.rst.txt @@ -0,0 +1,68 @@ +The ATTiny +========== + +In a Nutshell +------------- + +The ATTiny841 MCU works as: + +- Battery voltage and current monitor/gauge +- System current monitor +- Lid sensor + +The Atmel ATTiny841 (U16) is a 8-bit microcontroller that uses very little power and is always on when there is battery power in the system. +Its job is to keep track of how much current is going in and out of the battery and what voltage the battery has. It does this with the help of the voltage/current monitor chip INA260 that is connected to the ATTiny via I2C. + +Communcation +------------ + +The ATTiny is permanently connected to the i.MX6 UART2 (/dev/ttymxc1 in Linux). If you want to interrupt this connection, you can desolder resistors R48 and R50. + +The ATTiny firmware configures its serial port to 9600 baud 8N1. You can talk to it using the program screen (or another serial terminal): + +.. code-block:: shell + + screen /dev/ttymxc1 9600 + +It accepts commands in the form of a single letter and sends a string in response. The current commands are: + +- *p*: Get battery power information (estimated capacity in amp hours, voltage, current) +- *l*: Get lid state (0: open, 1: closed) +- *h*: Get hall sensor raw analog value +- *r*: Reset the battery capacity counter to 10Ah (TODO: make it possible to set a value) + +Undervoltage Protection (UVLO) +------------------------------ + +The microcontroller is supposed to detect a dangerously low voltage on the battery and switch the 5V boost converter off via its PWRON output when the voltage is below 2.8V. This way, the system will not draw power from the battery until it is charged to a reasonable level again. This functionality is still being tested and not activated in the beta boards. + +Lid Sensor +---------- + +The ATTiny also senses if the lid is open or closed. A hall effect sensor is connected to pins 3 and 4 (analog input). The lid is considered closed when a magnet is close to the sensor. The ATTiny outputs the string "lid_open" via its serial port which can wake the i.MX6 up from sleep. + +Flashing the Firmware +--------------------- + +You can find the source code of the firmware_ in the folder "reform-attiny-fw" of the Reform source repository. + +To change (flash) the firmware of the ATTiny, you need an Atmel ISP (In System Programmer) compatible programmer/cable. An easy way is to use an Arduino to emulate_ an ISP. + +The relevant pins of J34 on the Reform motherboard for connecting the ISP cable are as follows: + +Upper row (left to right): + +- **1** SCK +- **3** MISO +- **5** MOSI +- **7** GND + +Lower row (left to right): + +- **2** Not connected +- **4** Not connected +- **6** Not connected +- **8** RESET + +.. _emulate: https://www.arduino.cc/en/Tutorial/ArduinoISP +.. _firmware: https://github.com/mntmn/reform/reform-attiny-fw diff --git a/handbook/build/html/_sources/quickstart/index.rst.txt b/handbook/build/html/_sources/quickstart/index.rst.txt @@ -19,7 +19,7 @@ To log in, enter "root" as the username and "reform" as the password. From this console environment, you can: -- Format an mSATA SSD drive (if installed) and install an OS to it +- Format an mSATA SSD drive (if you put one in the mSATA slot) and install an OS to it - Secure the root account and create standard user accounts - Try some preinstalled graphical demos - Inspect or repair the system diff --git a/handbook/build/html/_sources/thermal/index.rst.txt b/handbook/build/html/_sources/thermal/index.rst.txt @@ -0,0 +1,28 @@ +Thermal +======= + +The main source of heat inside Reform is the i.MX6 SoC and its memory chips. Most of the heat goes into the blue passive heatsink that is glued to it. A fan which is mounted to the bottom plate then blows air over the heatsink into the direction of the ports, where it can escape through gaps in the case. + +The fan is needed to push hot air out of the case, preventing overheating of the system. Normally, its full power is only needed when the system is under heavy load, for example when the GPU (3D graphics processor) is very active or all 4 cores are busy compiling code. The fan should turn on to full power when the SoC temperature is over 65 degrees celcius. + +One of the three fan cables (yellow) connects to the PWM1 pin of the i.MX6. The fan's speed can be controlled via pulse width modulation. This is usually the job of the reformd script, which monitors the core temperature and sets the fan to full power when the temperature is over 65 degrees Celcius. + +To check the temperature of the system, you can use the command: + +.. code-block:: shell + + cat /sys/class/thermal/thermal_zone0/temp + +The following is an example of commands that reformd uses to change the fan speed (in this instance, to set it to 75%): + +.. code-block:: shell + + # make the first PWM device available + echo 0 > /sys/class/pwm/pwmchip1/export + # define what a full period is + echo 10000 > /sys/class/pwm/pwmchip1/pwm0/period + # set how much of this period should be in the "ON" state (75%) + echo 7500 > /sys/class/pwm/pwmchip1/pwm0/duty_cycle + # enable the PWM output + echo 1 > /sys/class/pwm/pwmchip1/pwm0/enable + diff --git a/handbook/build/html/_sources/trackball/index.rst.txt b/handbook/build/html/_sources/trackball/index.rst.txt @@ -0,0 +1,33 @@ +The Trackball +============= + +The trackball uses the same microcontroller and LUFA framework as the keyboard_, but instead of scanning a matrix of switches, it gets X and Y movement coordinates from the PMW3360DM-T2QU optical sensor that is connected via SPI. + +Wheel Mode, Middle Click +------------------------ + +The trackball firmware has a special "wheel mode" that allows you to use it like a mouse wheel for scrolling or to perform a middle mouse click. + +You can enter wheel mode by pressing the left button and then pressing the right button while keeping the left button pressed. Release both buttons. Rolling the ball up and down will send wheel up/down commands. Clicking the right button will perform a middle click. Clicking the left button will exit wheel mode. + +Firmware +-------- + +You can find the Reform trackball firmware_ in the source folder "reform-trackball-fw". + +The trackball firmware is based on the LUFA USB device library and implements a USB HID Mouse. To modify the behaviour of the trackball, edit the file Mouse.c and rebuild the firmware by typing the following command in a terminal: + +.. code-block:: shell + + make + +As with the keyboard, the trackball's MCU has to be in "Atmega DFU bootloader" USB mode. This is achieved by shorting the pins HWB and GND with a jumper and then briefly shorting the RESET pin to ground. The pins are marked on the silkscreen of the main trackball PCB. + +After a reset with HWB pulled to ground, The trackball will reappear as a Atmel DFU bootloader USB device. You can then upload your new firmware by executing: + +.. code-block:: shell + + ./flash.sh + +.. _firmware: https://github.com/mntmn/reform/reform-trackball-fw +.. _keyboard: ../keyboard/index.html diff --git a/handbook/build/html/_static/documentation_options.js b/handbook/build/html/_static/documentation_options.js @@ -1,5 +1,5 @@ var DOCUMENTATION_OPTIONS = { - URL_ROOT: '', + URL_ROOT: document.getElementById("documentation_options").getAttribute('data-url_root'), VERSION: '', LANGUAGE: 'None', COLLAPSE_INDEX: false, diff --git a/handbook/build/html/boot/index.html b/handbook/build/html/boot/index.html @@ -9,13 +9,14 @@ <title>System Boot Details — Reform documentation</title> <link rel="stylesheet" href="../_static/mntstyle.css" type="text/css" /> <link rel="stylesheet" href="../_static/pygments.css" type="text/css" /> - <script type="text/javascript" src="../_static/documentation_options.js"></script> + <script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script> <script type="text/javascript" src="../_static/jquery.js"></script> <script type="text/javascript" src="../_static/underscore.js"></script> <script type="text/javascript" src="../_static/doctools.js"></script> <link rel="index" title="Index" href="../genindex.html" /> <link rel="search" title="Search" href="../search.html" /> - <link rel="prev" title="The Motherboard" href="../motherboard/index.html" /> + <link rel="next" title="Debugging" href="../debug/index.html" /> + <link rel="prev" title="Thermal" href="../thermal/index.html" /> </head><body> <div class="related" role="navigation" aria-label="related navigation"> <h3>Navigation</h3> @@ -24,7 +25,10 @@ <a href="../genindex.html" title="General Index" accesskey="I">index</a></li> <li class="right" > - <a href="../motherboard/index.html" title="The Motherboard" + <a href="../debug/index.html" title="Debugging" + accesskey="N">next</a> |</li> + <li class="right" > + <a href="../thermal/index.html" title="Thermal" accesskey="P">previous</a> |</li> <li class="nav-item nav-item-0"><a href="../index.html">Reform documentation</a> »</li> </ul> @@ -40,7 +44,7 @@ <div class="section" id="powering-up"> <h2>Powering Up<a class="headerlink" href="#powering-up" title="Permalink to this headline">¶</a></h2> <p>When the power switch is turned on, the TinyRex circuit receives power. If it is happy with the applied voltages (POWEROK signals are present), the green LED on the TinyRex module will light up. If only the red LED lights up, there is a problem with the power supply.</p> -<p>Next, the i.MX6 chip will jump to internal boot ROM code at memory address _0x00000000_. The boot ROM looks for an SD card on port SD1 and reads the DCD (Device Configuration Data) table from physical address 0x400 (1024 decimal, or the second physical block) on the SD card. This means that you can only use the MBR partition scheme on the boot disk, as it only occupies the first disk block. The more modern GPT partition format could work in theory, but most GPT tools and parsers do not understand GPT structures where the second block is in an alternative location.</p> +<p>Next, the i.MX6 chip will jump to internal boot ROM code at memory address <em>0x00000000</em>. The boot ROM looks for an SD card on port SD1 and reads the DCD (Device Configuration Data) table from physical address 0x400 (1024 decimal, or the second physical block) on the SD card. This means that you can only use the MBR partition scheme on the boot disk, as it only occupies the first disk block. The more modern GPT partition format could work in theory, but most GPT tools and parsers do not understand GPT structures where the second block is in an alternative location.</p> <p>We recommend to use the SD card as a boot and rescue disk, and set up an mSATA SSD disk with your actual operating system and data. You can then use alternative partition schemes and encryption.</p> <p>Reform ships with U-Boot. It is installed onto the SD card and includes the DCD block that configures the DDR memory parameters and clocks.</p> </div> @@ -112,12 +116,17 @@ fdt resize <li class="toctree-l1"><a class="reference internal" href="../quickstart/index.html">Quick Start</a></li> <li class="toctree-l1"><a class="reference internal" href="../case/index.html">The Case</a></li> <li class="toctree-l1"><a class="reference internal" href="../motherboard/index.html">The Motherboard</a></li> +<li class="toctree-l1"><a class="reference internal" href="../motherboard/attiny.html">The ATTiny</a></li> +<li class="toctree-l1"><a class="reference internal" href="../keyboard/index.html">The Keyboard</a></li> +<li class="toctree-l1"><a class="reference internal" href="../trackball/index.html">The Trackball</a></li> +<li class="toctree-l1"><a class="reference internal" href="../thermal/index.html">Thermal</a></li> <li class="toctree-l1 current"><a class="current reference internal" href="#">System Boot Details</a><ul> <li class="toctree-l2"><a class="reference internal" href="#powering-up">Powering Up</a></li> <li class="toctree-l2"><a class="reference internal" href="#u-boot">U-Boot</a></li> <li class="toctree-l2"><a class="reference internal" href="#booting-the-linux-kernel">Booting the Linux Kernel</a></li> </ul> </li> +<li class="toctree-l1"><a class="reference internal" href="../debug/index.html">Debugging</a></li> </ul> </div> @@ -131,14 +140,17 @@ fdt resize <a href="../genindex.html" title="General Index" >index</a></li> <li class="right" > - <a href="../motherboard/index.html" title="The Motherboard" + <a href="../debug/index.html" title="Debugging" + >next</a> |</li> + <li class="right" > + <a href="../thermal/index.html" title="Thermal" >previous</a> |</li> <li class="nav-item nav-item-0"><a href="../index.html">Reform documentation</a> »</li> </ul> </div> <div class="footer" role="contentinfo"> © Copyright 2018, Lukas F. Hartmann (mntmn). - Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.4. + Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.9. </div> </body> </html> \ No newline at end of file diff --git a/handbook/build/html/case/index.html b/handbook/build/html/case/index.html @@ -9,7 +9,7 @@ <title>The Case — Reform documentation</title> <link rel="stylesheet" href="../_static/mntstyle.css" type="text/css" /> <link rel="stylesheet" href="../_static/pygments.css" type="text/css" /> - <script type="text/javascript" src="../_static/documentation_options.js"></script> + <script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script> <script type="text/javascript" src="../_static/jquery.js"></script> <script type="text/javascript" src="../_static/underscore.js"></script> <script type="text/javascript" src="../_static/doctools.js"></script> @@ -110,7 +110,12 @@ </ul> </li> <li class="toctree-l1"><a class="reference internal" href="../motherboard/index.html">The Motherboard</a></li> +<li class="toctree-l1"><a class="reference internal" href="../motherboard/attiny.html">The ATTiny</a></li> +<li class="toctree-l1"><a class="reference internal" href="../keyboard/index.html">The Keyboard</a></li> +<li class="toctree-l1"><a class="reference internal" href="../trackball/index.html">The Trackball</a></li> +<li class="toctree-l1"><a class="reference internal" href="../thermal/index.html">Thermal</a></li> <li class="toctree-l1"><a class="reference internal" href="../boot/index.html">System Boot Details</a></li> +<li class="toctree-l1"><a class="reference internal" href="../debug/index.html">Debugging</a></li> </ul> </div> @@ -134,7 +139,7 @@ </div> <div class="footer" role="contentinfo"> © Copyright 2018, Lukas F. Hartmann (mntmn). - Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.4. + Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.9. </div> </body> </html> \ No newline at end of file diff --git a/handbook/build/html/debug/index.html b/handbook/build/html/debug/index.html @@ -0,0 +1,118 @@ + +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta http-equiv="X-UA-Compatible" content="IE=Edge" /> + <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> + <title>Debugging — Reform documentation</title> + <link rel="stylesheet" href="../_static/mntstyle.css" type="text/css" /> + <link rel="stylesheet" href="../_static/pygments.css" type="text/css" /> + <script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script> + <script type="text/javascript" src="../_static/jquery.js"></script> + <script type="text/javascript" src="../_static/underscore.js"></script> + <script type="text/javascript" src="../_static/doctools.js"></script> + <link rel="index" title="Index" href="../genindex.html" /> + <link rel="search" title="Search" href="../search.html" /> + <link rel="prev" title="System Boot Details" href="../boot/index.html" /> + </head><body> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="../genindex.html" title="General Index" + accesskey="I">index</a></li> + <li class="right" > + <a href="../boot/index.html" title="System Boot Details" + accesskey="P">previous</a> |</li> + <li class="nav-item nav-item-0"><a href="../index.html">Reform documentation</a> »</li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body" role="main"> + + <div class="section" id="debugging"> +<h1>Debugging<a class="headerlink" href="#debugging" title="Permalink to this headline">¶</a></h1> +<div class="section" id="power"> +<h2>Power<a class="headerlink" href="#power" title="Permalink to this headline">¶</a></h2> +<p>The TinyRex module has a red and a green LED. Both have to light up to signal good power.</p> +<p>To troubleshoot power, disconnect the internal battery and all internal and external peripherals, connect the 5V wall adapter. If you want to unplug the TinyRex module, you should take the motherboard out of the case first.</p> +<p>Turn the power switch on. Get a multimeter and find the following voltages in the system:</p> +<ul class="simple"> +<li><strong>5V</strong> The main input rail. Can be found on pin 1 of J25 or J29.</li> +<li><strong>3.3V</strong> The big regulator U4 (AP1501A-33) turns 5V into 3.3V. Check test point TP3 next to the big coil L2.</li> +<li><strong>2.5V</strong> Regulated by U11 (LP3962EMP-2.5). Check TP5 next to it.</li> +<li><strong>1.5V</strong> Regulated by U13. Check TP12. Needed for PCIe.</li> +<li><strong>1.1V</strong> Regulated by U5 near the USB hub U9. Check TP6.</li> +</ul> +<p>If voltages are way off, there can be a short somewhere on the board which usually generates heat.</p> +</div> +<div class="section" id="serial-console"> +<h2>Serial Console<a class="headerlink" href="#serial-console" title="Permalink to this headline">¶</a></h2> +<p>The motherboard connector labelled CONSOLE is a serial port (UART) to which U-Boot and the Linux kernel output diagnostic information on startup. The baud rate is 115200.</p> +<p>Wire up a generic USB-to-UART adapter to the following pins of J25 (pin 1 is next to the J25 label):</p> +<ul class="simple"> +<li><strong>1</strong> 5V, don’t connect</li> +<li><strong>2</strong> UART1_TXD, connect to RX of your adapter</li> +<li><strong>3</strong> UART1_RXD, connect to TX of your adapter</li> +<li><strong>4</strong> UART1_RTS, don’t connect</li> +<li><strong>5</strong> UART1_CTS, don’t connect</li> +<li><strong>6</strong> GND, connect to GND of your adapter</li> +</ul> +<p>Then, use a terminal program such as screen on your host computer:</p> +<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>screen /dev/ttyUSB0 <span class="m">115200</span> +</pre></div> +</div> +<p>If you then switch on Reform with a prepared SD card inserted, you should see the U-Boot console in <em>screen</em>.</p> +</div> +</div> + + + </div> + </div> + </div> + <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> + <div class="sphinxsidebarwrapper"> +<h3><a href="../index.html">Table Of Contents</a></h3> +<ul class="current"> +<li class="toctree-l1"><a class="reference internal" href="../quickstart/index.html">Quick Start</a></li> +<li class="toctree-l1"><a class="reference internal" href="../case/index.html">The Case</a></li> +<li class="toctree-l1"><a class="reference internal" href="../motherboard/index.html">The Motherboard</a></li> +<li class="toctree-l1"><a class="reference internal" href="../motherboard/attiny.html">The ATTiny</a></li> +<li class="toctree-l1"><a class="reference internal" href="../keyboard/index.html">The Keyboard</a></li> +<li class="toctree-l1"><a class="reference internal" href="../trackball/index.html">The Trackball</a></li> +<li class="toctree-l1"><a class="reference internal" href="../thermal/index.html">Thermal</a></li> +<li class="toctree-l1"><a class="reference internal" href="../boot/index.html">System Boot Details</a></li> +<li class="toctree-l1 current"><a class="current reference internal" href="#">Debugging</a><ul> +<li class="toctree-l2"><a class="reference internal" href="#power">Power</a></li> +<li class="toctree-l2"><a class="reference internal" href="#serial-console">Serial Console</a></li> +</ul> +</li> +</ul> + + </div> + </div> + <div class="clearer"></div> + </div> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="../genindex.html" title="General Index" + >index</a></li> + <li class="right" > + <a href="../boot/index.html" title="System Boot Details" + >previous</a> |</li> + <li class="nav-item nav-item-0"><a href="../index.html">Reform documentation</a> »</li> + </ul> + </div> + <div class="footer" role="contentinfo"> + © Copyright 2018, Lukas F. Hartmann (mntmn). + Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.9. + </div> + </body> +</html> +\ No newline at end of file diff --git a/handbook/build/html/genindex.html b/handbook/build/html/genindex.html @@ -10,7 +10,7 @@ <title>Index — Reform documentation</title> <link rel="stylesheet" href="_static/mntstyle.css" type="text/css" /> <link rel="stylesheet" href="_static/pygments.css" type="text/css" /> - <script type="text/javascript" src="_static/documentation_options.js"></script> + <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script> <script type="text/javascript" src="_static/jquery.js"></script> <script type="text/javascript" src="_static/underscore.js"></script> <script type="text/javascript" src="_static/doctools.js"></script> @@ -50,7 +50,12 @@ <li class="toctree-l1"><a class="reference internal" href="quickstart/index.html">Quick Start</a></li> <li class="toctree-l1"><a class="reference internal" href="case/index.html">The Case</a></li> <li class="toctree-l1"><a class="reference internal" href="motherboard/index.html">The Motherboard</a></li> +<li class="toctree-l1"><a class="reference internal" href="motherboard/attiny.html">The ATTiny</a></li> +<li class="toctree-l1"><a class="reference internal" href="keyboard/index.html">The Keyboard</a></li> +<li class="toctree-l1"><a class="reference internal" href="trackball/index.html">The Trackball</a></li> +<li class="toctree-l1"><a class="reference internal" href="thermal/index.html">Thermal</a></li> <li class="toctree-l1"><a class="reference internal" href="boot/index.html">System Boot Details</a></li> +<li class="toctree-l1"><a class="reference internal" href="debug/index.html">Debugging</a></li> </ul> </div> @@ -68,7 +73,7 @@ </div> <div class="footer" role="contentinfo"> © Copyright 2018, Lukas F. Hartmann (mntmn). - Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.4. + Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.9. </div> </body> </html> \ No newline at end of file diff --git a/handbook/build/html/index.html b/handbook/build/html/index.html @@ -9,7 +9,7 @@ <title>MNT Reform Operator Handbook — Reform documentation</title> <link rel="stylesheet" href="_static/mntstyle.css" type="text/css" /> <link rel="stylesheet" href="_static/pygments.css" type="text/css" /> - <script type="text/javascript" src="_static/documentation_options.js"></script> + <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script> <script type="text/javascript" src="_static/jquery.js"></script> <script type="text/javascript" src="_static/underscore.js"></script> <script type="text/javascript" src="_static/doctools.js"></script> @@ -65,12 +65,37 @@ <li class="toctree-l2"><a class="reference internal" href="motherboard/index.html#audio">Audio</a></li> </ul> </li> +<li class="toctree-l1"><a class="reference internal" href="motherboard/attiny.html">The ATTiny</a><ul> +<li class="toctree-l2"><a class="reference internal" href="motherboard/attiny.html#in-a-nutshell">In a Nutshell</a></li> +<li class="toctree-l2"><a class="reference internal" href="motherboard/attiny.html#communcation">Communcation</a></li> +<li class="toctree-l2"><a class="reference internal" href="motherboard/attiny.html#undervoltage-protection-uvlo">Undervoltage Protection (UVLO)</a></li> +<li class="toctree-l2"><a class="reference internal" href="motherboard/attiny.html#lid-sensor">Lid Sensor</a></li> +<li class="toctree-l2"><a class="reference internal" href="motherboard/attiny.html#flashing-the-firmware">Flashing the Firmware</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="keyboard/index.html">The Keyboard</a><ul> +<li class="toctree-l2"><a class="reference internal" href="keyboard/index.html#firmware">Firmware</a></li> +<li class="toctree-l2"><a class="reference internal" href="keyboard/index.html#replacing-a-keycap">Replacing a Keycap</a></li> +<li class="toctree-l2"><a class="reference internal" href="keyboard/index.html#replacing-a-keyswitch">Replacing a Keyswitch</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="trackball/index.html">The Trackball</a><ul> +<li class="toctree-l2"><a class="reference internal" href="trackball/index.html#wheel-mode-middle-click">Wheel Mode, Middle Click</a></li> +<li class="toctree-l2"><a class="reference internal" href="trackball/index.html#firmware">Firmware</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="thermal/index.html">Thermal</a></li> <li class="toctree-l1"><a class="reference internal" href="boot/index.html">System Boot Details</a><ul> <li class="toctree-l2"><a class="reference internal" href="boot/index.html#powering-up">Powering Up</a></li> <li class="toctree-l2"><a class="reference internal" href="boot/index.html#u-boot">U-Boot</a></li> <li class="toctree-l2"><a class="reference internal" href="boot/index.html#booting-the-linux-kernel">Booting the Linux Kernel</a></li> </ul> </li> +<li class="toctree-l1"><a class="reference internal" href="debug/index.html">Debugging</a><ul> +<li class="toctree-l2"><a class="reference internal" href="debug/index.html#power">Power</a></li> +<li class="toctree-l2"><a class="reference internal" href="debug/index.html#serial-console">Serial Console</a></li> +</ul> +</li> </ul> </div> </div> @@ -87,7 +112,12 @@ <li class="toctree-l1"><a class="reference internal" href="quickstart/index.html">Quick Start</a></li> <li class="toctree-l1"><a class="reference internal" href="case/index.html">The Case</a></li> <li class="toctree-l1"><a class="reference internal" href="motherboard/index.html">The Motherboard</a></li> +<li class="toctree-l1"><a class="reference internal" href="motherboard/attiny.html">The ATTiny</a></li> +<li class="toctree-l1"><a class="reference internal" href="keyboard/index.html">The Keyboard</a></li> +<li class="toctree-l1"><a class="reference internal" href="trackball/index.html">The Trackball</a></li> +<li class="toctree-l1"><a class="reference internal" href="thermal/index.html">Thermal</a></li> <li class="toctree-l1"><a class="reference internal" href="boot/index.html">System Boot Details</a></li> +<li class="toctree-l1"><a class="reference internal" href="debug/index.html">Debugging</a></li> </ul> </div> @@ -108,7 +138,7 @@ </div> <div class="footer" role="contentinfo"> © Copyright 2018, Lukas F. Hartmann (mntmn). - Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.4. + Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.9. </div> </body> </html> \ No newline at end of file diff --git a/handbook/build/html/keyboard/index.html b/handbook/build/html/keyboard/index.html @@ -0,0 +1,121 @@ + +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta http-equiv="X-UA-Compatible" content="IE=Edge" /> + <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> + <title>The Keyboard — Reform documentation</title> + <link rel="stylesheet" href="../_static/mntstyle.css" type="text/css" /> + <link rel="stylesheet" href="../_static/pygments.css" type="text/css" /> + <script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script> + <script type="text/javascript" src="../_static/jquery.js"></script> + <script type="text/javascript" src="../_static/underscore.js"></script> + <script type="text/javascript" src="../_static/doctools.js"></script> + <link rel="index" title="Index" href="../genindex.html" /> + <link rel="search" title="Search" href="../search.html" /> + <link rel="next" title="The Trackball" href="../trackball/index.html" /> + <link rel="prev" title="The ATTiny" href="../motherboard/attiny.html" /> + </head><body> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="../genindex.html" title="General Index" + accesskey="I">index</a></li> + <li class="right" > + <a href="../trackball/index.html" title="The Trackball" + accesskey="N">next</a> |</li> + <li class="right" > + <a href="../motherboard/attiny.html" title="The ATTiny" + accesskey="P">previous</a> |</li> + <li class="nav-item nav-item-0"><a href="../index.html">Reform documentation</a> »</li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body" role="main"> + + <div class="section" id="the-keyboard"> +<h1>The Keyboard<a class="headerlink" href="#the-keyboard" title="Permalink to this headline">¶</a></h1> +<p>The keyboard is a row/column matrix scanner with anti-ghosting diodes on each switch. Each row and column is connected to one pin of the <a class="reference external" href="http://ww1.microchip.com/downloads/en/DeviceDoc/Atmel-7766-8-bit-AVR-ATmega16U4-32U4_Datasheet.pdf">ATMega32U4</a> 8-bit microcontroller. This microcontroller runs a firmware based on <a class="reference external" href="http://www.fourwalledcubicle.com/files/LUFA/Doc/170418/html/">LUFA</a>. This converts the scanned out keycodes to the USB HID protocol.</p> +<div class="section" id="firmware"> +<h2>Firmware<a class="headerlink" href="#firmware" title="Permalink to this headline">¶</a></h2> +<p>You can find the Reform keyboard <a class="reference external" href="https://github.com/mntmn/reform/reform-keyboard-fw">firmware</a> in the source folder “reform-keyboard-fw”.</p> +<p>To modify the scancodes of the keyboard matrix, edit the file Keyboard.c and rebuild the firmware by typing the following command in a terminal:</p> +<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>make +</pre></div> +</div> +<p>To be able to flash the firmware to the keyboard, the ATMega has to be in a special mode where it identifies as an “Atmega DFU bootloader” USB device. This is achieved by shorting the pins HWB and GND with a jumper and then briefly shorting the RESET pin to ground.</p> +<p>The RESET pin is pin 2 of J1, pin 1 is GND.</p> +<p>HWB and GND are pins 3 and 4 of J3, respectively. Start counting at the “J3” label.</p> +<p>The keyboard will reappear as a Atmel DFU bootloader USB device. You can then upload your new firmware by executing:</p> +<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>./flash.sh +</pre></div> +</div> +</div> +<div class="section" id="replacing-a-keycap"> +<h2>Replacing a Keycap<a class="headerlink" href="#replacing-a-keycap" title="Permalink to this headline">¶</a></h2> +<p>The keycaps of the Reform beta units are printed with Clear Resin on Formlabs Form2 printers and then sanded by hand. Small irregularities are normal and a result of this process. The stems of the square 1x1 keycaps are slightly wider than the stems of other keycaps to make them more stable. This makes them harder to remove without breaking a stem. If a stem breaks inside of the keyswitch, you’ll have to replace the keyswitch (see the following section).</p> +<p>To pull out bigger keycaps, use pincers and try to push them between the top of the switch and the cap and wiggle very carefully and evenly until you can pull out the cap.</p> +<p>There are some companies who produce “standard” Cherry ML keycaps, such as <a class="reference external" href="https://www.gmk-electronic-design.de/en.html">GMK</a>.</p> +</div> +<div class="section" id="replacing-a-keyswitch"> +<h2>Replacing a Keyswitch<a class="headerlink" href="#replacing-a-keyswitch" title="Permalink to this headline">¶</a></h2> +<p>Only 2 of the 4 Cherry ML switch pins are soldered in to make it easier to swap switches with just a soldering iron. Set your iron/station to 380 degrees and dissolve the solder of one pin. Try to pull out the corresponding side of the switch from the top while continuing to heat the pin. Repeat the same for the other pin and go back and forth until you can remove the switch.</p> +<p>Replace with model Cherry ML1A-11JW.</p> +</div> +</div> + + + </div> + </div> + </div> + <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> + <div class="sphinxsidebarwrapper"> +<h3><a href="../index.html">Table Of Contents</a></h3> +<ul class="current"> +<li class="toctree-l1"><a class="reference internal" href="../quickstart/index.html">Quick Start</a></li> +<li class="toctree-l1"><a class="reference internal" href="../case/index.html">The Case</a></li> +<li class="toctree-l1"><a class="reference internal" href="../motherboard/index.html">The Motherboard</a></li> +<li class="toctree-l1"><a class="reference internal" href="../motherboard/attiny.html">The ATTiny</a></li> +<li class="toctree-l1 current"><a class="current reference internal" href="#">The Keyboard</a><ul> +<li class="toctree-l2"><a class="reference internal" href="#firmware">Firmware</a></li> +<li class="toctree-l2"><a class="reference internal" href="#replacing-a-keycap">Replacing a Keycap</a></li> +<li class="toctree-l2"><a class="reference internal" href="#replacing-a-keyswitch">Replacing a Keyswitch</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="../trackball/index.html">The Trackball</a></li> +<li class="toctree-l1"><a class="reference internal" href="../thermal/index.html">Thermal</a></li> +<li class="toctree-l1"><a class="reference internal" href="../boot/index.html">System Boot Details</a></li> +<li class="toctree-l1"><a class="reference internal" href="../debug/index.html">Debugging</a></li> +</ul> + + </div> + </div> + <div class="clearer"></div> + </div> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="../genindex.html" title="General Index" + >index</a></li> + <li class="right" > + <a href="../trackball/index.html" title="The Trackball" + >next</a> |</li> + <li class="right" > + <a href="../motherboard/attiny.html" title="The ATTiny" + >previous</a> |</li> + <li class="nav-item nav-item-0"><a href="../index.html">Reform documentation</a> »</li> + </ul> + </div> + <div class="footer" role="contentinfo"> + © Copyright 2018, Lukas F. Hartmann (mntmn). + Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.9. + </div> + </body> +</html> +\ No newline at end of file diff --git a/handbook/build/html/motherboard/attiny.html b/handbook/build/html/motherboard/attiny.html @@ -0,0 +1,150 @@ + +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta http-equiv="X-UA-Compatible" content="IE=Edge" /> + <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> + <title>The ATTiny — Reform documentation</title> + <link rel="stylesheet" href="../_static/mntstyle.css" type="text/css" /> + <link rel="stylesheet" href="../_static/pygments.css" type="text/css" /> + <script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script> + <script type="text/javascript" src="../_static/jquery.js"></script> + <script type="text/javascript" src="../_static/underscore.js"></script> + <script type="text/javascript" src="../_static/doctools.js"></script> + <link rel="index" title="Index" href="../genindex.html" /> + <link rel="search" title="Search" href="../search.html" /> + <link rel="next" title="The Keyboard" href="../keyboard/index.html" /> + <link rel="prev" title="The Motherboard" href="index.html" /> + </head><body> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="../genindex.html" title="General Index" + accesskey="I">index</a></li> + <li class="right" > + <a href="../keyboard/index.html" title="The Keyboard" + accesskey="N">next</a> |</li> + <li class="right" > + <a href="index.html" title="The Motherboard" + accesskey="P">previous</a> |</li> + <li class="nav-item nav-item-0"><a href="../index.html">Reform documentation</a> »</li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body" role="main"> + + <div class="section" id="the-attiny"> +<h1>The ATTiny<a class="headerlink" href="#the-attiny" title="Permalink to this headline">¶</a></h1> +<div class="section" id="in-a-nutshell"> +<h2>In a Nutshell<a class="headerlink" href="#in-a-nutshell" title="Permalink to this headline">¶</a></h2> +<p>The ATTiny841 MCU works as:</p> +<ul class="simple"> +<li>Battery voltage and current monitor/gauge</li> +<li>System current monitor</li> +<li>Lid sensor</li> +</ul> +<p>The Atmel ATTiny841 (U16) is a 8-bit microcontroller that uses very little power and is always on when there is battery power in the system. +Its job is to keep track of how much current is going in and out of the battery and what voltage the battery has. It does this with the help of the voltage/current monitor chip INA260 that is connected to the ATTiny via I2C.</p> +</div> +<div class="section" id="communcation"> +<h2>Communcation<a class="headerlink" href="#communcation" title="Permalink to this headline">¶</a></h2> +<p>The ATTiny is permanently connected to the i.MX6 UART2 (/dev/ttymxc1 in Linux). If you want to interrupt this connection, you can desolder resistors R48 and R50.</p> +<p>The ATTiny firmware configures its serial port to 9600 baud 8N1. You can talk to it using the program screen (or another serial terminal):</p> +<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>screen /dev/ttymxc1 <span class="m">9600</span> +</pre></div> +</div> +<p>It accepts commands in the form of a single letter and sends a string in response. The current commands are:</p> +<ul class="simple"> +<li><em>p</em>: Get battery power information (estimated capacity in amp hours, voltage, current)</li> +<li><em>l</em>: Get lid state (0: open, 1: closed)</li> +<li><em>h</em>: Get hall sensor raw analog value</li> +<li><em>r</em>: Reset the battery capacity counter to 10Ah (TODO: make it possible to set a value)</li> +</ul> +</div> +<div class="section" id="undervoltage-protection-uvlo"> +<h2>Undervoltage Protection (UVLO)<a class="headerlink" href="#undervoltage-protection-uvlo" title="Permalink to this headline">¶</a></h2> +<p>The microcontroller is supposed to detect a dangerously low voltage on the battery and switch the 5V boost converter off via its PWRON output when the voltage is below 2.8V. This way, the system will not draw power from the battery until it is charged to a reasonable level again. This functionality is still being tested and not activated in the beta boards.</p> +</div> +<div class="section" id="lid-sensor"> +<h2>Lid Sensor<a class="headerlink" href="#lid-sensor" title="Permalink to this headline">¶</a></h2> +<p>The ATTiny also senses if the lid is open or closed. A hall effect sensor is connected to pins 3 and 4 (analog input). The lid is considered closed when a magnet is close to the sensor. The ATTiny outputs the string “lid_open” via its serial port which can wake the i.MX6 up from sleep.</p> +</div> +<div class="section" id="flashing-the-firmware"> +<h2>Flashing the Firmware<a class="headerlink" href="#flashing-the-firmware" title="Permalink to this headline">¶</a></h2> +<p>You can find the source code of the <a class="reference external" href="https://github.com/mntmn/reform/reform-attiny-fw">firmware</a> in the folder “reform-attiny-fw” of the Reform source repository.</p> +<p>To change (flash) the firmware of the ATTiny, you need an Atmel ISP (In System Programmer) compatible programmer/cable. An easy way is to use an Arduino to <a class="reference external" href="https://www.arduino.cc/en/Tutorial/ArduinoISP">emulate</a> an ISP.</p> +<p>The relevant pins of J34 on the Reform motherboard for connecting the ISP cable are as follows:</p> +<p>Upper row (left to right):</p> +<ul class="simple"> +<li><strong>1</strong> SCK</li> +<li><strong>3</strong> MISO</li> +<li><strong>5</strong> MOSI</li> +<li><strong>7</strong> GND</li> +</ul> +<p>Lower row (left to right):</p> +<ul class="simple"> +<li><strong>2</strong> Not connected</li> +<li><strong>4</strong> Not connected</li> +<li><strong>6</strong> Not connected</li> +<li><strong>8</strong> RESET</li> +</ul> +</div> +</div> + + + </div> + </div> + </div> + <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> + <div class="sphinxsidebarwrapper"> +<h3><a href="../index.html">Table Of Contents</a></h3> +<ul class="current"> +<li class="toctree-l1"><a class="reference internal" href="../quickstart/index.html">Quick Start</a></li> +<li class="toctree-l1"><a class="reference internal" href="../case/index.html">The Case</a></li> +<li class="toctree-l1"><a class="reference internal" href="index.html">The Motherboard</a></li> +<li class="toctree-l1 current"><a class="current reference internal" href="#">The ATTiny</a><ul> +<li class="toctree-l2"><a class="reference internal" href="#in-a-nutshell">In a Nutshell</a></li> +<li class="toctree-l2"><a class="reference internal" href="#communcation">Communcation</a></li> +<li class="toctree-l2"><a class="reference internal" href="#undervoltage-protection-uvlo">Undervoltage Protection (UVLO)</a></li> +<li class="toctree-l2"><a class="reference internal" href="#lid-sensor">Lid Sensor</a></li> +<li class="toctree-l2"><a class="reference internal" href="#flashing-the-firmware">Flashing the Firmware</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="../keyboard/index.html">The Keyboard</a></li> +<li class="toctree-l1"><a class="reference internal" href="../trackball/index.html">The Trackball</a></li> +<li class="toctree-l1"><a class="reference internal" href="../thermal/index.html">Thermal</a></li> +<li class="toctree-l1"><a class="reference internal" href="../boot/index.html">System Boot Details</a></li> +<li class="toctree-l1"><a class="reference internal" href="../debug/index.html">Debugging</a></li> +</ul> + + </div> + </div> + <div class="clearer"></div> + </div> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="../genindex.html" title="General Index" + >index</a></li> + <li class="right" > + <a href="../keyboard/index.html" title="The Keyboard" + >next</a> |</li> + <li class="right" > + <a href="index.html" title="The Motherboard" + >previous</a> |</li> + <li class="nav-item nav-item-0"><a href="../index.html">Reform documentation</a> »</li> + </ul> + </div> + <div class="footer" role="contentinfo"> + © Copyright 2018, Lukas F. Hartmann (mntmn). + Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.9. + </div> + </body> +</html> +\ No newline at end of file diff --git a/handbook/build/html/motherboard/index.html b/handbook/build/html/motherboard/index.html @@ -9,13 +9,13 @@ <title>The Motherboard — Reform documentation</title> <link rel="stylesheet" href="../_static/mntstyle.css" type="text/css" /> <link rel="stylesheet" href="../_static/pygments.css" type="text/css" /> - <script type="text/javascript" src="../_static/documentation_options.js"></script> + <script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script> <script type="text/javascript" src="../_static/jquery.js"></script> <script type="text/javascript" src="../_static/underscore.js"></script> <script type="text/javascript" src="../_static/doctools.js"></script> <link rel="index" title="Index" href="../genindex.html" /> <link rel="search" title="Search" href="../search.html" /> - <link rel="next" title="System Boot Details" href="../boot/index.html" /> + <link rel="next" title="The ATTiny" href="attiny.html" /> <link rel="prev" title="The Case" href="../case/index.html" /> </head><body> <div class="related" role="navigation" aria-label="related navigation"> @@ -25,7 +25,7 @@ <a href="../genindex.html" title="General Index" accesskey="I">index</a></li> <li class="right" > - <a href="../boot/index.html" title="System Boot Details" + <a href="attiny.html" title="The ATTiny" accesskey="N">next</a> |</li> <li class="right" > <a href="../case/index.html" title="The Case" @@ -92,7 +92,12 @@ <li class="toctree-l2"><a class="reference internal" href="#audio">Audio</a></li> </ul> </li> +<li class="toctree-l1"><a class="reference internal" href="attiny.html">The ATTiny</a></li> +<li class="toctree-l1"><a class="reference internal" href="../keyboard/index.html">The Keyboard</a></li> +<li class="toctree-l1"><a class="reference internal" href="../trackball/index.html">The Trackball</a></li> +<li class="toctree-l1"><a class="reference internal" href="../thermal/index.html">Thermal</a></li> <li class="toctree-l1"><a class="reference internal" href="../boot/index.html">System Boot Details</a></li> +<li class="toctree-l1"><a class="reference internal" href="../debug/index.html">Debugging</a></li> </ul> </div> @@ -106,7 +111,7 @@ <a href="../genindex.html" title="General Index" >index</a></li> <li class="right" > - <a href="../boot/index.html" title="System Boot Details" + <a href="attiny.html" title="The ATTiny" >next</a> |</li> <li class="right" > <a href="../case/index.html" title="The Case" @@ -116,7 +121,7 @@ </div> <div class="footer" role="contentinfo"> © Copyright 2018, Lukas F. Hartmann (mntmn). - Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.4. + Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.9. </div> </body> </html> \ No newline at end of file diff --git a/handbook/build/html/objects.inv b/handbook/build/html/objects.inv @@ -2,6 +2,5 @@ # Project: Reform # Version: # The remainder of this file is compressed using zlib. -xmM0 =E.[B4CK-3r{a -.٭J [)H>t; j#Á ʊ-;';`1Q5&zHԗb1Få& ¥,Fm0 -CF0L$FΏM$gSuh>[O!거&wlׯxc -\ No newline at end of file +xmAR E} +.0ZnݩYhYc hT D UBH""߿w^W5s^K#pV̛. @cGI?L8O=*+ LwĞIܖ; Um?Ҙ6a%~BuWq~쓾լȢ7=(Ê 4,s Ay%ݴ6a ohͩȦ}?.>p EBs{<+:|D.#;.R-AQc_ʈ[C(&/u +\ No newline at end of file diff --git a/handbook/build/html/quickstart/index.html b/handbook/build/html/quickstart/index.html @@ -9,7 +9,7 @@ <title>Quick Start — Reform documentation</title> <link rel="stylesheet" href="../_static/mntstyle.css" type="text/css" /> <link rel="stylesheet" href="../_static/pygments.css" type="text/css" /> - <script type="text/javascript" src="../_static/documentation_options.js"></script> + <script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script> <script type="text/javascript" src="../_static/jquery.js"></script> <script type="text/javascript" src="../_static/underscore.js"></script> <script type="text/javascript" src="../_static/doctools.js"></script> @@ -51,7 +51,7 @@ <p>To log in, enter “root” as the username and “reform” as the password.</p> <p>From this console environment, you can:</p> <ul class="simple"> -<li>Format an mSATA SSD drive (if installed) and install an OS to it</li> +<li>Format an mSATA SSD drive (if you put one in the mSATA slot) and install an OS to it</li> <li>Secure the root account and create standard user accounts</li> <li>Try some preinstalled graphical demos</li> <li>Inspect or repair the system</li> @@ -69,7 +69,12 @@ <li class="toctree-l1 current"><a class="current reference internal" href="#">Quick Start</a></li> <li class="toctree-l1"><a class="reference internal" href="../case/index.html">The Case</a></li> <li class="toctree-l1"><a class="reference internal" href="../motherboard/index.html">The Motherboard</a></li> +<li class="toctree-l1"><a class="reference internal" href="../motherboard/attiny.html">The ATTiny</a></li> +<li class="toctree-l1"><a class="reference internal" href="../keyboard/index.html">The Keyboard</a></li> +<li class="toctree-l1"><a class="reference internal" href="../trackball/index.html">The Trackball</a></li> +<li class="toctree-l1"><a class="reference internal" href="../thermal/index.html">Thermal</a></li> <li class="toctree-l1"><a class="reference internal" href="../boot/index.html">System Boot Details</a></li> +<li class="toctree-l1"><a class="reference internal" href="../debug/index.html">Debugging</a></li> </ul> </div> @@ -93,7 +98,7 @@ </div> <div class="footer" role="contentinfo"> © Copyright 2018, Lukas F. Hartmann (mntmn). - Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.4. + Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.9. </div> </body> </html> \ No newline at end of file diff --git a/handbook/build/html/search.html b/handbook/build/html/search.html @@ -9,7 +9,7 @@ <title>Search — Reform documentation</title> <link rel="stylesheet" href="_static/mntstyle.css" type="text/css" /> <link rel="stylesheet" href="_static/pygments.css" type="text/css" /> - <script type="text/javascript" src="_static/documentation_options.js"></script> + <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script> <script type="text/javascript" src="_static/jquery.js"></script> <script type="text/javascript" src="_static/underscore.js"></script> <script type="text/javascript" src="_static/doctools.js"></script> @@ -73,7 +73,12 @@ <li class="toctree-l1"><a class="reference internal" href="quickstart/index.html">Quick Start</a></li> <li class="toctree-l1"><a class="reference internal" href="case/index.html">The Case</a></li> <li class="toctree-l1"><a class="reference internal" href="motherboard/index.html">The Motherboard</a></li> +<li class="toctree-l1"><a class="reference internal" href="motherboard/attiny.html">The ATTiny</a></li> +<li class="toctree-l1"><a class="reference internal" href="keyboard/index.html">The Keyboard</a></li> +<li class="toctree-l1"><a class="reference internal" href="trackball/index.html">The Trackball</a></li> +<li class="toctree-l1"><a class="reference internal" href="thermal/index.html">Thermal</a></li> <li class="toctree-l1"><a class="reference internal" href="boot/index.html">System Boot Details</a></li> +<li class="toctree-l1"><a class="reference internal" href="debug/index.html">Debugging</a></li> </ul> </div> @@ -91,7 +96,7 @@ </div> <div class="footer" role="contentinfo"> © Copyright 2018, Lukas F. Hartmann (mntmn). - Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.4. + Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.9. </div> </body> </html> \ No newline at end of file diff --git a/handbook/build/html/searchindex.js b/handbook/build/html/searchindex.js @@ -1 +1 @@ -Search.setIndex({docnames:["boot/index","case/index","index","motherboard/index","quickstart/index"],envversion:53,filenames:["boot/index.rst","case/index.rst","index.rst","motherboard/index.rst","quickstart/index.rst"],objects:{},objnames:{},objtypes:{},terms:{"0x10008000":0,"0x18000000":0,"0x400":0,"0xffffffff":0,"256m":0,"256mb":0,"case":2,"default":[0,4],"switch":[0,1,4],"try":4,DTS:0,For:[0,4],The:[0,2,4],Then:4,_0x00000000_:0,account:4,acryl:1,act:1,activ:4,actual:0,adapt:4,addr:0,address:0,after:1,air:1,all:[0,4],alloc:0,allow:0,also:[0,1],altern:0,anyth:0,appli:0,assembl:1,ath9k:0,attach:1,audio:2,automat:4,back:2,base:0,batteri:[1,4],befor:1,besid:0,between:1,bezel:1,big:0,blob:0,block:0,board:0,boot:[2,4],bootarg:0,bootstrap:0,bootz:0,both:0,bottom:[2,4],box:2,build:0,cabl:[1,4],call:0,can:[0,4],card:[0,4],central:4,charg:4,chip:0,circuit:0,clock:0,close:1,closur:2,cma:0,code:0,com:0,command:0,compil:0,config:0,configur:0,connect:[1,4],connector:4,consol:4,contain:1,continu:0,contribut:0,corner:[1,4],could:0,cover:1,cpu:4,creat:[0,4],data:0,dcd:0,ddr:0,debian:4,decim:0,demo:4,detail:2,detect:1,dev:0,devic:[0,1,4],diagnost:4,didn:0,disabl:0,disk:0,displai:[1,2,4],doe:0,done:0,drive:[0,4],driver:0,dtb:0,dts:0,effect:1,either:4,electron:1,els:0,encrypt:0,end:4,enter:4,environ:4,ethernet:2,etnaviv:0,everyth:4,expand:0,expans:0,expos:1,express:0,ext4:0,ext4load:0,fail:0,fan:1,far:0,fat:0,fatload:0,fdt:0,fdt_high:0,file:0,first:0,format:[0,4],freebsd:0,from:[0,1,4],front:[2,4],github:0,gnu:4,gpt:0,gpu:0,graphic:4,green:0,greet:4,grid:2,guid:0,hall:1,happi:0,happili:0,harddisk:0,has:[0,1],have:0,header:1,helper:0,hing:1,hold:1,hole:1,http:0,imx6qp:0,imx:0,includ:0,inform:4,initi:0,inner:1,insert:1,inspect:[0,4],instal:[0,4],intak:1,intern:[0,1,4],interrupt:[0,4],isol:1,itself:0,j12:1,j14:1,j15:1,j22:1,j26:1,j33:1,j34:1,jump:0,just:0,kernel:[2,4],keyboard:2,keypress:4,l104:0,lasercut:1,led:0,left:1,lid:[1,4],lifepo4:[1,4],light:0,like:0,line:0,linux:[2,4],list:0,load:0,locat:[0,4],log:4,login:4,logo:4,look:0,lower:1,lvd:1,magnet:1,main:2,manag:0,manual:0,maximum:0,mbr:0,mean:0,memori:0,messag:0,mini:0,mkkernel:0,mkreform:0,mkuboot:0,mmc:0,mmcblk0p1:0,mnt:4,mntmn:0,mntreform:0,modern:0,modul:0,more:0,most:[0,1],motherboard:[1,2,4],mount:1,msata:[0,4],msi:0,mx6:0,mx6qp:0,need:0,netbsd:0,next:0,noinitrd:0,nomsi:0,normal:0,occupi:0,onli:0,onto:[0,1],open:1,openbsd:0,oper:[0,4],other:[0,1],palm:1,paramet:0,parser:0,part:[0,1],partit:0,pass:[0,1],password:4,pci:0,pcie:[0,2],physic:0,place:1,plate:2,pleas:0,plug:4,pocket:1,pool:0,port:[0,1],power:[1,2,4],powerok:0,preinstal:4,present:[0,4],press:1,problem:0,processor:4,prompt:4,push:4,quick:2,ram:0,read:0,reason:4,reattach:4,receiv:0,recommend:0,red:0,reform:[0,1,4],repair:4,rescu:0,resiz:0,rest:1,result:0,right:[1,4],rom:0,root:[0,4],rootwait:0,run:0,safeti:4,same:0,sandwich:1,schemat:2,scheme:0,screen:2,screw:1,script:0,sd1:0,second:0,secur:[1,4],sens:1,sensor:1,serv:1,set:0,setenv:0,shell:0,ship:0,should:4,show:4,signal:[0,1],size:0,slide:1,slot:1,soc:0,some:[0,4],sourc:0,specifi:0,ssd:[0,4],standard:4,start:[0,2],step:0,storag:2,strap:1,structur:0,suppli:0,support:[0,2],system:[2,4],tabl:0,tell:0,test:0,them:0,theoret:0,theori:0,thi:[0,1,4],thin:1,though:0,through:1,time:0,tinyrex:0,tool:0,top:2,trackbal:1,tree:0,turn:0,understand:0,unscrew:4,upper:4,usb:[0,1,2],use:[0,4],user:4,usernam:4,using:0,util:0,vent:1,via:1,voltag:0,volum:0,wait:0,wall:4,want:0,well:1,when:0,where:0,white:4,wifi:0,without:0,work:0,would:0,write:0,you:[0,4],your:0,zimag:0},titles:["System Boot Details","The Case","MNT Reform Operator Handbook","The Motherboard","Quick Start"],titleterms:{"case":1,The:[1,3],audio:3,back:1,boot:0,bottom:1,box:1,closur:1,content:2,detail:0,displai:3,ethernet:3,front:1,grid:1,handbook:2,kernel:0,keyboard:1,linux:0,main:1,mnt:2,motherboard:3,oper:2,pcie:3,plate:1,power:[0,3],quick:4,reform:2,schemat:3,screen:1,start:4,storag:3,support:1,system:0,tabl:2,top:1,usb:3}}) -\ No newline at end of file +Search.setIndex({docnames:["TODO","boot/index","case/index","debug/index","index","keyboard/index","motherboard/attiny","motherboard/index","quickstart/index","thermal/index","trackball/index"],envversion:55,filenames:["TODO.rst","boot/index.rst","case/index.rst","debug/index.rst","index.rst","keyboard/index.rst","motherboard/attiny.rst","motherboard/index.rst","quickstart/index.rst","thermal/index.rst","trackball/index.rst"],objects:{},objnames:{},objtypes:{},terms:{"0x00000000":1,"0x10008000":1,"0x18000000":1,"0x400":1,"0xffffffff":1,"10ah":6,"11jw":5,"1366x768":0,"1368x768":0,"1920x1200":0,"1x1":5,"256m":1,"256mb":1,"8n1":6,"break":5,"case":[0,3,4,9],"class":[0,9],"default":[1,8],"export":9,"function":6,"new":[0,5,10],"short":[3,5,10],"switch":[1,2,3,5,6,8,10],"try":[5,8],"while":[5,10],DTS:[0,1],For:[1,8],Its:6,Not:6,One:9,The:[0,1,3,4,8,9],Then:[3,8],There:5,abl:5,acceler:0,accept:6,account:8,achiev:[5,10],acryl:2,act:2,activ:[6,8,9],actual:1,adapt:[3,8],addr:1,address:1,after:[2,10],again:6,air:[2,9],all:[1,3,8,9],alloc:1,allow:[1,10],also:[0,1,2,6],altern:1,alwai:6,amd:0,amp:6,amplifi:0,analog:6,ani:0,anoth:6,anti:5,anyth:1,ap1501a:3,appli:1,arduino:6,assembl:2,ath9k:1,atmega32u4:5,atmega:[5,10],atmel:[5,6,10],attach:2,attini:4,attiny841:6,audio:4,automat:8,avail:9,avoid:0,back:[4,5],ball:10,base:[1,5,10],batteri:[0,2,3,6,8],baud:[3,6],befor:2,behaviour:10,being:6,below:6,besid:1,beta:[5,6],between:[2,5],bezel:2,big:[1,3],bigger:5,bit:[5,6],blob:1,block:1,blow:9,blue:9,board:[1,3,6],boost:6,boot:[0,3,4,8],bootarg:1,bootload:[5,10],bootrom:0,bootstrap:1,bootz:1,both:[1,3,10],bottom:[4,8,9],box:4,briefli:[5,10],bright:0,brightnessctl:0,build:[0,1],busi:9,button:10,cabl:[2,6,8,9],call:1,can:[0,1,3,5,6,8,9,10],cap:5,capac:6,card:[0,1,3,8],carefulli:5,cat:[0,9],celciu:9,central:8,chang:[0,6,9],charg:[6,8],check:[3,9],cherri:5,chip:[1,6,9],circuit:1,clear:5,click:4,clock:1,close:[2,6],closur:4,cma:1,code:[1,6,9],coil:3,column:5,com:[0,1],command:[0,1,5,6,9,10],communc:4,compani:5,compat:[0,6],compil:[1,9],comput:3,config:1,configur:[0,1,6],connect:[0,2,3,5,6,8,9,10],connector:[3,8],consid:6,consol:[0,4,8],contain:2,continu:[1,5],contribut:1,control:9,convert:[5,6],coordin:10,core:9,corner:[2,8],correspond:5,could:1,count:5,counter:6,cover:2,cpu:[0,8],creat:[1,8],csi:0,current:6,curs:0,danger:6,data:1,dcd:1,ddr:1,debian:8,debug:4,decim:1,decod:0,defin:9,degre:[5,9],demo:8,desold:6,detail:4,detect:[2,6],dev:[0,1,3,6],devic:[0,1,2,5,8,9,10],dfu:[5,10],diagnost:[3,8],didn:1,diod:5,direct:9,disabl:1,disconnect:3,discret:0,disk:1,displai:[0,2,4,8],dissolv:5,doe:[0,1,6],don:3,done:1,down:10,draw:6,drive:[1,8],driver:[0,1],dsi:0,dtb:1,dts:1,duty_cycl:9,each:5,easi:6,easier:5,echo:9,edit:[5,10],effect:[2,6],either:8,electron:2,els:1,empti:0,emul:6,enabl:9,encrypt:1,end:8,enter:[8,10],environ:8,escap:9,estim:6,ethernet:[0,4],etnaviv:1,evenli:5,everyth:8,exampl:9,execut:[5,10],exit:10,expand:1,expans:1,expos:2,express:1,ext4:1,ext4load:1,extern:3,fail:1,fan:[2,9],faq:0,far:[0,1],fat:1,fatload:1,fdt:1,fdt_high:1,file:[1,5,10],find:[3,5,6,10],firmwar:4,first:[1,3,9],flash:[4,5,10],folder:[5,6,10],follow:[3,5,6,9,10],form2:5,form:6,format:[1,8],formlab:5,forth:5,found:3,framework:10,freebsd:1,from:[1,2,5,6,8,10],front:[4,8],full:[0,9],game:0,gap:9,gaug:6,gener:3,get:[3,6,10],ghost:5,git:0,github:[0,1],glu:9,gmk:5,gnd:[3,5,6,10],gnu:8,goe:9,going:6,good:3,gpio:0,gpt:1,gpu:[1,9],graphic:[0,8,9],green:[1,3],greet:8,grid:4,ground:[5,10],guid:1,hall:[2,6],hand:5,handl:0,happi:1,happili:1,harddisk:1,harder:5,hardwar:0,has:[0,1,2,3,5,6,10],have:[0,1,3,5],hdmi:0,header:[0,2],headphon:0,heat:[3,5,9],heatsink:9,heavi:9,help:6,helper:1,hid:[5,10],hing:2,hold:2,hole:2,host:3,hot:9,hour:6,how:[0,6,9],http:[0,1],huawei:0,hub:3,hwb:[5,10],i2c:[0,6],identifi:5,implement:10,imx6qp:1,imx:1,ina260:6,includ:[0,1],inform:[3,6,8],initi:1,inner:2,input:[0,3,6],insert:[2,3],insid:[5,9],inspect:[1,8],instal:[1,8],instanc:9,instead:10,intak:2,intern:[0,1,2,3,8],internet:0,interrupt:[1,6,8],iron:5,irregular:5,isol:2,isp:6,issu:0,its:[6,9],itself:[0,1],j12:2,j14:2,j15:2,j22:2,j25:3,j26:2,j29:3,j33:2,j34:[2,6],jack:0,job:[6,9],jump:1,jumper:[5,10],just:[1,5],keep:[6,10],kernel:[3,4,8],keyboard:[0,4,10],keycap:[0,4],keycod:5,keypress:8,keyswitch:4,l104:1,label:[0,3,5],lasercut:2,led:[1,3],left:[2,6,10],letter:6,level:6,librari:10,lid:[2,4,8],lid_open:6,lifepo4:[2,8],light:[1,3],like:[0,1,10],line:[0,1],linux:[3,4,6,8],list:1,littl:6,load:[1,9],locat:[1,8],log:8,login:8,logo:8,look:1,low:6,lower:[2,6],lp3962emp:3,lte:0,lufa:[5,10],lvd:2,magnet:[2,6],main:[3,4,9,10],make:[0,5,6,9,10],manag:1,manual:1,mark:10,matrix:[5,10],maximum:[0,1],mbr:1,mcu:[6,10],mean:1,memori:[1,9],messag:1,microcontrol:[5,6,10],microphon:0,middl:4,mini:1,miso:6,mkkernel:1,mkreform:1,mkuboot:1,ml1a:5,mmc:1,mmcblk0p1:1,mnt:8,mntmn:[0,1],mntreform:1,mode:[0,4,5],model:5,modem:0,modern:1,modifi:[5,10],modul:[0,1,3,9],monitor:[6,9],more:[1,5],mosi:6,most:[1,2,9],motherboard:[0,2,3,4,6,8],mount:[2,9],mous:10,movement:10,msata:[1,8],msi:1,much:[6,9],multimet:3,multipl:0,mx6:[1,6,9],mx6qp:1,need:[1,3,6,9],netbsd:1,next:[1,3],noinitrd:1,nomsi:1,normal:[1,5,9],nutshel:4,nvidia:0,occupi:1,off:[3,6],one:[5,8],onli:[0,1,5,9],onto:[1,2],open:[2,6],openbsd:1,opengl:0,oper:[1,8],optic:10,other:[1,2,5],out:[0,3,5,6,9],output:[0,3,6,9],over:9,overh:9,own:0,palm:2,paramet:1,parser:1,part:[0,1,2],partit:1,pass:[1,2],passiv:9,password:8,pcb:10,pci:1,pcie:[1,3,4],perform:10,period:9,peripher:3,perman:6,physic:1,pin:[3,5,6,9,10],pincer:5,place:2,plate:[4,9],pleas:1,plug:8,pmw3360dm:10,pocket:2,point:3,pool:1,port:[0,1,2,3,6,9],possibl:6,power:[2,4,6,8,9],powerok:1,preinstal:8,prepar:3,present:[0,1,8],press:[2,10],prevent:9,print:[0,5],printer:5,problem:[0,1],process:5,processor:[8,9],produc:5,program:[3,6],programm:6,prompt:8,proprietari:0,protect:4,protocol:5,pull:[5,10],puls:9,push:[5,8,9],put:8,pwm0:9,pwm1:9,pwm:9,pwmchip1:9,pwron:6,quick:4,r48:6,r50:6,rail:3,ram:1,raspberri:0,rate:3,raw:6,read:1,reappear:[5,10],reason:[6,8],reattach:8,rebuild:[5,10],receiv:1,recommend:1,red:[1,3],reform:[0,1,2,3,5,6,8,9,10],reformd:9,regul:3,releas:10,relev:6,remov:5,repair:8,repeat:5,replac:4,repositori:[0,6],rescu:1,reset:[5,6,10],resin:5,resistor:6,resiz:1,resolut:0,respect:5,respons:6,rest:2,result:[1,5],right:[2,6,8,10],roll:10,rom:[0,1],root:[1,8],rootwait:1,row:[5,6],run:[0,1,5],safeti:8,same:[1,5,10],sand:5,sandwich:2,scan:[5,10],scancod:5,scanner:5,schemat:[0,4],scheme:1,sck:6,screen:[0,3,4,6],screw:2,script:[1,9],scroll:10,sd1:1,second:1,section:5,secur:[2,8],see:[3,5],send:[6,10],sens:[2,6],sensor:[2,4,10],serial:[0,4,6],serv:2,set:[1,5,6,9],setenv:1,setup:0,shell:1,ship:1,should:[3,8,9],show:8,side:5,signal:[1,2,3],silkscreen:10,sim:0,singl:6,size:1,sleep:6,slide:2,slightli:5,slot:[2,8],small:5,soc:[1,9],softwar:0,solder:5,some:[1,5,8],somewher:3,sourc:[1,5,6,9,10],speaker:0,special:[5,10],specifi:1,speed:9,spi:[0,10],squar:5,ssd:[1,8],stabl:5,standard:[5,8],start:[1,4,5],startup:3,state:[6,9],station:5,stem:5,step:1,stereo:0,still:6,storag:4,strap:2,string:6,structur:1,suppli:1,support:[1,4],suppos:6,swap:5,sys:[0,9],system:[0,3,4,6,8,9],t2qu:10,tabl:1,take:3,talk:6,tell:1,temp:[0,9],temperatur:[0,9],termin:[0,3,5,6,10],test:[0,1,3,6],than:5,them:[1,5],theoret:1,theori:1,thermal:[0,4],thermal_zone0:[0,9],thi:[1,2,5,6,8,9,10],thin:2,though:1,three:9,through:[2,9],time:1,tinyrex:[0,1,3],todo:6,tool:1,top:[4,5],tp12:3,tp3:3,tp5:3,tp6:3,track:6,trackbal:[0,2,4],tree:[0,1],troubleshoot:3,tty:0,ttymxc1:6,ttyusb0:3,turn:[1,3,9],type:[5,10],u11:3,u13:3,u16:6,uart1_ct:3,uart1_rt:3,uart1_rxd:3,uart1_txd:3,uart2:6,uart:3,under:9,understand:1,undervoltag:4,unit:5,unlock:0,unplug:3,unscrew:8,until:[5,6],upload:[5,10],upper:[6,8],usb:[0,1,2,3,4,5,10],use:[0,1,3,5,6,8,9,10],user:8,usernam:8,uses:[6,9,10],using:[1,6],usual:[3,9],util:1,uvlo:4,valu:6,vent:2,veri:[5,6,9],via:[2,6,9,10],video:0,voltag:[1,3,6],volum:1,wai:[3,6],wait:1,wake:6,wall:[3,8],want:[1,3,6],wayland:0,well:2,what:[0,6,9],wheel:4,when:[1,6,9],where:[0,1,5,9],which:[3,6,9],white:8,who:5,wicd:0,wider:5,width:[0,9],wifi:[0,1],wiggl:5,wire:3,without:[1,5],work:[0,1,6],workaround:0,would:1,write:1,wwan:0,x86:0,xorg:0,xyz999:0,xyz:0,yellow:9,you:[0,1,3,5,6,8,9,10],your:[0,1,3,5,10],zimag:1},titles:["topics todo","System Boot Details","The Case","Debugging","MNT Reform Operator Handbook","The Keyboard","The ATTiny","The Motherboard","Quick Start","Thermal","The Trackball"],titleterms:{"case":2,The:[2,5,6,7,10],attini:6,audio:7,back:2,boot:1,bottom:2,box:2,click:10,closur:2,communc:6,consol:3,content:4,debug:3,detail:1,displai:7,ethernet:7,firmwar:[5,6,10],flash:6,front:2,grid:2,handbook:4,kernel:1,keyboard:[2,5],keycap:5,keyswitch:5,lid:6,linux:1,main:2,middl:10,mnt:4,mode:10,motherboard:7,nutshel:6,oper:4,pcie:7,plate:2,power:[1,3,7],protect:6,quick:8,reform:4,replac:5,schemat:7,screen:2,sensor:6,serial:3,start:8,storag:7,support:2,system:1,tabl:4,thermal:9,todo:0,top:2,topic:0,trackbal:10,undervoltag:6,usb:7,uvlo:6,wheel:10}}) +\ No newline at end of file diff --git a/handbook/build/html/thermal/index.html b/handbook/build/html/thermal/index.html @@ -0,0 +1,107 @@ + +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta http-equiv="X-UA-Compatible" content="IE=Edge" /> + <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> + <title>Thermal — Reform documentation</title> + <link rel="stylesheet" href="../_static/mntstyle.css" type="text/css" /> + <link rel="stylesheet" href="../_static/pygments.css" type="text/css" /> + <script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script> + <script type="text/javascript" src="../_static/jquery.js"></script> + <script type="text/javascript" src="../_static/underscore.js"></script> + <script type="text/javascript" src="../_static/doctools.js"></script> + <link rel="index" title="Index" href="../genindex.html" /> + <link rel="search" title="Search" href="../search.html" /> + <link rel="next" title="System Boot Details" href="../boot/index.html" /> + <link rel="prev" title="The Trackball" href="../trackball/index.html" /> + </head><body> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="../genindex.html" title="General Index" + accesskey="I">index</a></li> + <li class="right" > + <a href="../boot/index.html" title="System Boot Details" + accesskey="N">next</a> |</li> + <li class="right" > + <a href="../trackball/index.html" title="The Trackball" + accesskey="P">previous</a> |</li> + <li class="nav-item nav-item-0"><a href="../index.html">Reform documentation</a> »</li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body" role="main"> + + <div class="section" id="thermal"> +<h1>Thermal<a class="headerlink" href="#thermal" title="Permalink to this headline">¶</a></h1> +<p>The main source of heat inside Reform is the i.MX6 SoC and its memory chips. Most of the heat goes into the blue passive heatsink that is glued to it. A fan which is mounted to the bottom plate then blows air over the heatsink into the direction of the ports, where it can escape through gaps in the case.</p> +<p>The fan is needed to push hot air out of the case, preventing overheating of the system. Normally, its full power is only needed when the system is under heavy load, for example when the GPU (3D graphics processor) is very active or all 4 cores are busy compiling code. The fan should turn on to full power when the SoC temperature is over 65 degrees celcius.</p> +<p>One of the three fan cables (yellow) connects to the PWM1 pin of the i.MX6. The fan’s speed can be controlled via pulse width modulation. This is usually the job of the reformd script, which monitors the core temperature and sets the fan to full power when the temperature is over 65 degrees Celcius.</p> +<p>To check the temperature of the system, you can use the command:</p> +<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>cat /sys/class/thermal/thermal_zone0/temp +</pre></div> +</div> +<p>The following is an example of commands that reformd uses to change the fan speed (in this instance, to set it to 75%):</p> +<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span><span class="c1"># make the first PWM device available</span> +<span class="nb">echo</span> <span class="m">0</span> > /sys/class/pwm/pwmchip1/export +<span class="c1"># define what a full period is</span> +<span class="nb">echo</span> <span class="m">10000</span> > /sys/class/pwm/pwmchip1/pwm0/period +<span class="c1"># set how much of this period should be in the "ON" state (75%)</span> +<span class="nb">echo</span> <span class="m">7500</span> > /sys/class/pwm/pwmchip1/pwm0/duty_cycle +<span class="c1"># enable the PWM output</span> +<span class="nb">echo</span> <span class="m">1</span> > /sys/class/pwm/pwmchip1/pwm0/enable +</pre></div> +</div> +</div> + + + </div> + </div> + </div> + <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> + <div class="sphinxsidebarwrapper"> +<h3><a href="../index.html">Table Of Contents</a></h3> +<ul class="current"> +<li class="toctree-l1"><a class="reference internal" href="../quickstart/index.html">Quick Start</a></li> +<li class="toctree-l1"><a class="reference internal" href="../case/index.html">The Case</a></li> +<li class="toctree-l1"><a class="reference internal" href="../motherboard/index.html">The Motherboard</a></li> +<li class="toctree-l1"><a class="reference internal" href="../motherboard/attiny.html">The ATTiny</a></li> +<li class="toctree-l1"><a class="reference internal" href="../keyboard/index.html">The Keyboard</a></li> +<li class="toctree-l1"><a class="reference internal" href="../trackball/index.html">The Trackball</a></li> +<li class="toctree-l1 current"><a class="current reference internal" href="#">Thermal</a></li> +<li class="toctree-l1"><a class="reference internal" href="../boot/index.html">System Boot Details</a></li> +<li class="toctree-l1"><a class="reference internal" href="../debug/index.html">Debugging</a></li> +</ul> + + </div> + </div> + <div class="clearer"></div> + </div> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="../genindex.html" title="General Index" + >index</a></li> + <li class="right" > + <a href="../boot/index.html" title="System Boot Details" + >next</a> |</li> + <li class="right" > + <a href="../trackball/index.html" title="The Trackball" + >previous</a> |</li> + <li class="nav-item nav-item-0"><a href="../index.html">Reform documentation</a> »</li> + </ul> + </div> + <div class="footer" role="contentinfo"> + © Copyright 2018, Lukas F. Hartmann (mntmn). + Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.9. + </div> + </body> +</html> +\ No newline at end of file diff --git a/handbook/build/html/trackball/index.html b/handbook/build/html/trackball/index.html @@ -0,0 +1,112 @@ + +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta http-equiv="X-UA-Compatible" content="IE=Edge" /> + <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> + <title>The Trackball — Reform documentation</title> + <link rel="stylesheet" href="../_static/mntstyle.css" type="text/css" /> + <link rel="stylesheet" href="../_static/pygments.css" type="text/css" /> + <script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script> + <script type="text/javascript" src="../_static/jquery.js"></script> + <script type="text/javascript" src="../_static/underscore.js"></script> + <script type="text/javascript" src="../_static/doctools.js"></script> + <link rel="index" title="Index" href="../genindex.html" /> + <link rel="search" title="Search" href="../search.html" /> + <link rel="next" title="Thermal" href="../thermal/index.html" /> + <link rel="prev" title="The Keyboard" href="../keyboard/index.html" /> + </head><body> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="../genindex.html" title="General Index" + accesskey="I">index</a></li> + <li class="right" > + <a href="../thermal/index.html" title="Thermal" + accesskey="N">next</a> |</li> + <li class="right" > + <a href="../keyboard/index.html" title="The Keyboard" + accesskey="P">previous</a> |</li> + <li class="nav-item nav-item-0"><a href="../index.html">Reform documentation</a> »</li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body" role="main"> + + <div class="section" id="the-trackball"> +<h1>The Trackball<a class="headerlink" href="#the-trackball" title="Permalink to this headline">¶</a></h1> +<p>The trackball uses the same microcontroller and LUFA framework as the <a class="reference external" href="../keyboard/index.html">keyboard</a>, but instead of scanning a matrix of switches, it gets X and Y movement coordinates from the PMW3360DM-T2QU optical sensor that is connected via SPI.</p> +<div class="section" id="wheel-mode-middle-click"> +<h2>Wheel Mode, Middle Click<a class="headerlink" href="#wheel-mode-middle-click" title="Permalink to this headline">¶</a></h2> +<p>The trackball firmware has a special “wheel mode” that allows you to use it like a mouse wheel for scrolling or to perform a middle mouse click.</p> +<p>You can enter wheel mode by pressing the left button and then pressing the right button while keeping the left button pressed. Release both buttons. Rolling the ball up and down will send wheel up/down commands. Clicking the right button will perform a middle click. Clicking the left button will exit wheel mode.</p> +</div> +<div class="section" id="firmware"> +<h2>Firmware<a class="headerlink" href="#firmware" title="Permalink to this headline">¶</a></h2> +<p>You can find the Reform trackball <a class="reference external" href="https://github.com/mntmn/reform/reform-trackball-fw">firmware</a> in the source folder “reform-trackball-fw”.</p> +<p>The trackball firmware is based on the LUFA USB device library and implements a USB HID Mouse. To modify the behaviour of the trackball, edit the file Mouse.c and rebuild the firmware by typing the following command in a terminal:</p> +<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>make +</pre></div> +</div> +<p>As with the keyboard, the trackball’s MCU has to be in “Atmega DFU bootloader” USB mode. This is achieved by shorting the pins HWB and GND with a jumper and then briefly shorting the RESET pin to ground. The pins are marked on the silkscreen of the main trackball PCB.</p> +<p>After a reset with HWB pulled to ground, The trackball will reappear as a Atmel DFU bootloader USB device. You can then upload your new firmware by executing:</p> +<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>./flash.sh +</pre></div> +</div> +</div> +</div> + + + </div> + </div> + </div> + <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> + <div class="sphinxsidebarwrapper"> +<h3><a href="../index.html">Table Of Contents</a></h3> +<ul class="current"> +<li class="toctree-l1"><a class="reference internal" href="../quickstart/index.html">Quick Start</a></li> +<li class="toctree-l1"><a class="reference internal" href="../case/index.html">The Case</a></li> +<li class="toctree-l1"><a class="reference internal" href="../motherboard/index.html">The Motherboard</a></li> +<li class="toctree-l1"><a class="reference internal" href="../motherboard/attiny.html">The ATTiny</a></li> +<li class="toctree-l1"><a class="reference internal" href="../keyboard/index.html">The Keyboard</a></li> +<li class="toctree-l1 current"><a class="current reference internal" href="#">The Trackball</a><ul> +<li class="toctree-l2"><a class="reference internal" href="#wheel-mode-middle-click">Wheel Mode, Middle Click</a></li> +<li class="toctree-l2"><a class="reference internal" href="#firmware">Firmware</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="../thermal/index.html">Thermal</a></li> +<li class="toctree-l1"><a class="reference internal" href="../boot/index.html">System Boot Details</a></li> +<li class="toctree-l1"><a class="reference internal" href="../debug/index.html">Debugging</a></li> +</ul> + + </div> + </div> + <div class="clearer"></div> + </div> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="../genindex.html" title="General Index" + >index</a></li> + <li class="right" > + <a href="../thermal/index.html" title="Thermal" + >next</a> |</li> + <li class="right" > + <a href="../keyboard/index.html" title="The Keyboard" + >previous</a> |</li> + <li class="nav-item nav-item-0"><a href="../index.html">Reform documentation</a> »</li> + </ul> + </div> + <div class="footer" role="contentinfo"> + © Copyright 2018, Lukas F. Hartmann (mntmn). + Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.9. + </div> + </body> +</html> +\ No newline at end of file diff --git a/handbook/source/TODO.rst b/handbook/source/TODO.rst @@ -0,0 +1,55 @@ +topics todo +=========== + +faq +- how full/empty is the battery? +- how do i change the display brightness? + + brightnessctl s [1-7] + +- what temperature does the cpu/system have? + + cat /sys/class/thermal/thermal_zone0/temp + +- how do i use the proprietary hardware video decoder? + +- what does the boot rom do? +- where are the schematics for tinyRex? +- where are the schematics for REFORM? + + The schematics of the motherboard, keyboard and trackball are in the git repository https://github.com/mntmn/reform + +- how do i use an LTE modem/WWAN? + + The only modem tested so far is Huawei XYZ999. It presents itself as 5 serial ports (tty*) and an ethernet device in the system. + You have to connect with a serial terminal like screen to /dev/tty* and issue AT commands to unlock the SIM and connect to the internet. + +- how do i setup WiFi on the console? + + wicd-curses + +- can i use a discrete graphics card by nvidia or amd? +- what is the resolution of the display? + +The internal display has a resolution of 1366x768, but it is configured in the device tree (DTS) as 1368x768 to avoid problems with graphics drivers/hardware that can only handle multiples of 8 as the width. + +- what is the maximum resolution of HDMI? + +The maximum tested resolution of the HDMI output is 1920x1200. + +- how do i use the microphone input in the headphone jack? +- where are the speakers? + +Reform does not include any speakers, but a stereo speaker module is in the making. You can also build your own by connecting an amplifier and speakers to the motherboard header labelled Line Out. + +- how do i use SPI, I2C, GPIO? +- how do i use CSI, DSI? +- how can i use the bootrom's usb device mode? +- how do i print/make my own case part? +- how do i make a new keycap? +- how to use OpenGL/ES hardware acceleration in Xorg? +- how to use OpenGL/ES hardware acceleration in wayland? +- software/game XYZ does not work, is there a workaround? +- how can i run x86 software? +- how can i run Raspberry Pi compatible software? + diff --git a/handbook/source/boot/index.rst b/handbook/source/boot/index.rst @@ -6,7 +6,7 @@ Powering Up When the power switch is turned on, the TinyRex circuit receives power. If it is happy with the applied voltages (POWEROK signals are present), the green LED on the TinyRex module will light up. If only the red LED lights up, there is a problem with the power supply. -Next, the i.MX6 chip will jump to internal boot ROM code at memory address _0x00000000_. The boot ROM looks for an SD card on port SD1 and reads the DCD (Device Configuration Data) table from physical address 0x400 (1024 decimal, or the second physical block) on the SD card. This means that you can only use the MBR partition scheme on the boot disk, as it only occupies the first disk block. The more modern GPT partition format could work in theory, but most GPT tools and parsers do not understand GPT structures where the second block is in an alternative location. +Next, the i.MX6 chip will jump to internal boot ROM code at memory address *0x00000000*. The boot ROM looks for an SD card on port SD1 and reads the DCD (Device Configuration Data) table from physical address 0x400 (1024 decimal, or the second physical block) on the SD card. This means that you can only use the MBR partition scheme on the boot disk, as it only occupies the first disk block. The more modern GPT partition format could work in theory, but most GPT tools and parsers do not understand GPT structures where the second block is in an alternative location. We recommend to use the SD card as a boot and rescue disk, and set up an mSATA SSD disk with your actual operating system and data. You can then use alternative partition schemes and encryption. diff --git a/handbook/source/debug/index.rst b/handbook/source/debug/index.rst @@ -0,0 +1,42 @@ +Debugging +========= + +Power +----- + +The TinyRex module has a red and a green LED. Both have to light up to signal good power. + +To troubleshoot power, disconnect the internal battery and all internal and external peripherals, connect the 5V wall adapter. If you want to unplug the TinyRex module, you should take the motherboard out of the case first. + +Turn the power switch on. Get a multimeter and find the following voltages in the system: + +- **5V** The main input rail. Can be found on pin 1 of J25 or J29. +- **3.3V** The big regulator U4 (AP1501A-33) turns 5V into 3.3V. Check test point TP3 next to the big coil L2. +- **2.5V** Regulated by U11 (LP3962EMP-2.5). Check TP5 next to it. +- **1.5V** Regulated by U13. Check TP12. Needed for PCIe. +- **1.1V** Regulated by U5 near the USB hub U9. Check TP6. + +If voltages are way off, there can be a short somewhere on the board which usually generates heat. + +Serial Console +-------------- + +The motherboard connector labelled CONSOLE is a serial port (UART) to which U-Boot and the Linux kernel output diagnostic information on startup. The baud rate is 115200. + +Wire up a generic USB-to-UART adapter to the following pins of J25 (pin 1 is next to the J25 label): + +- **1** 5V, don't connect +- **2** UART1_TXD, connect to RX of your adapter +- **3** UART1_RXD, connect to TX of your adapter +- **4** UART1_RTS, don't connect +- **5** UART1_CTS, don't connect +- **6** GND, connect to GND of your adapter + +Then, use a terminal program such as screen on your host computer: + +.. code-block:: shell + + screen /dev/ttyUSB0 115200 + +If you then switch on Reform with a prepared SD card inserted, you should see the U-Boot console in *screen*. + diff --git a/handbook/source/index.rst b/handbook/source/index.rst @@ -17,4 +17,10 @@ Table of Contents quickstart/index case/index motherboard/index + motherboard/attiny + keyboard/index + trackball/index + thermal/index boot/index + debug/index + faq/index diff --git a/handbook/source/keyboard/index.rst b/handbook/source/keyboard/index.rst @@ -0,0 +1,48 @@ +The Keyboard +============ + +The keyboard is a row/column matrix scanner with anti-ghosting diodes on each switch. Each row and column is connected to one pin of the ATMega32U4_ 8-bit microcontroller. This microcontroller runs a firmware based on LUFA_. This converts the scanned out keycodes to the USB HID protocol. + +Firmware +-------- + +You can find the Reform keyboard firmware_ in the source folder "reform-keyboard-fw". + +To modify the scancodes of the keyboard matrix, edit the file Keyboard.c and rebuild the firmware by typing the following command in a terminal: + +.. code-block:: shell + + make + +To be able to flash the firmware to the keyboard, the ATMega has to be in a special mode where it identifies as an "Atmega DFU bootloader" USB device. This is achieved by shorting the pins HWB and GND with a jumper and then briefly shorting the RESET pin to ground. + +The RESET pin is pin 2 of J1, pin 1 is GND. + +HWB and GND are pins 3 and 4 of J3, respectively. Start counting at the "J3" label. + +The keyboard will reappear as a Atmel DFU bootloader USB device. You can then upload your new firmware by executing: + +.. code-block:: shell + + ./flash.sh + +Replacing a Keycap +------------------ + +The keycaps of the Reform beta units are printed with Clear Resin on Formlabs Form2 printers and then sanded by hand. Small irregularities are normal and a result of this process. The stems of the square 1x1 keycaps are slightly wider than the stems of other keycaps to make them more stable. This makes them harder to remove without breaking a stem. If a stem breaks inside of the keyswitch, you'll have to replace the keyswitch (see the following section). + +To pull out bigger keycaps, use pincers and try to push them between the top of the switch and the cap and wiggle very carefully and evenly until you can pull out the cap. + +There are some companies who produce "standard" Cherry ML keycaps, such as GMK_. + +Replacing a Keyswitch +--------------------- + +Only 2 of the 4 Cherry ML switch pins are soldered in to make it easier to swap switches with just a soldering iron. Set your iron/station to 380 degrees and dissolve the solder of one pin. Try to pull out the corresponding side of the switch from the top while continuing to heat the pin. Repeat the same for the other pin and go back and forth until you can remove the switch. + +Replace with model Cherry ML1A-11JW. + +.. _LUFA: http://www.fourwalledcubicle.com/files/LUFA/Doc/170418/html/ +.. _ATMega32U4: http://ww1.microchip.com/downloads/en/DeviceDoc/Atmel-7766-8-bit-AVR-ATmega16U4-32U4_Datasheet.pdf +.. _GMK: https://www.gmk-electronic-design.de/en.html +.. _firmware: https://github.com/mntmn/reform/reform-keyboard-fw diff --git a/handbook/source/motherboard/attiny.rst b/handbook/source/motherboard/attiny.rst @@ -0,0 +1,68 @@ +The ATTiny +========== + +In a Nutshell +------------- + +The ATTiny841 MCU works as: + +- Battery voltage and current monitor/gauge +- System current monitor +- Lid sensor + +The Atmel ATTiny841 (U16) is a 8-bit microcontroller that uses very little power and is always on when there is battery power in the system. +Its job is to keep track of how much current is going in and out of the battery and what voltage the battery has. It does this with the help of the voltage/current monitor chip INA260 that is connected to the ATTiny via I2C. + +Communcation +------------ + +The ATTiny is permanently connected to the i.MX6 UART2 (/dev/ttymxc1 in Linux). If you want to interrupt this connection, you can desolder resistors R48 and R50. + +The ATTiny firmware configures its serial port to 9600 baud 8N1. You can talk to it using the program screen (or another serial terminal): + +.. code-block:: shell + + screen /dev/ttymxc1 9600 + +It accepts commands in the form of a single letter and sends a string in response. The current commands are: + +- *p*: Get battery power information (estimated capacity in amp hours, voltage, current) +- *l*: Get lid state (0: open, 1: closed) +- *h*: Get hall sensor raw analog value +- *r*: Reset the battery capacity counter to 10Ah (TODO: make it possible to set a value) + +Undervoltage Protection (UVLO) +------------------------------ + +The microcontroller is supposed to detect a dangerously low voltage on the battery and switch the 5V boost converter off via its PWRON output when the voltage is below 2.8V. This way, the system will not draw power from the battery until it is charged to a reasonable level again. This functionality is still being tested and not activated in the beta boards. + +Lid Sensor +---------- + +The ATTiny also senses if the lid is open or closed. A hall effect sensor is connected to pins 3 and 4 (analog input). The lid is considered closed when a magnet is close to the sensor. The ATTiny outputs the string "lid_open" via its serial port which can wake the i.MX6 up from sleep. + +Flashing the Firmware +--------------------- + +You can find the source code of the firmware_ in the folder "reform-attiny-fw" of the Reform source repository. + +To change (flash) the firmware of the ATTiny, you need an Atmel ISP (In System Programmer) compatible programmer/cable. An easy way is to use an Arduino to emulate_ an ISP. + +The relevant pins of J34 on the Reform motherboard for connecting the ISP cable are as follows: + +Upper row (left to right): + +- **1** SCK +- **3** MISO +- **5** MOSI +- **7** GND + +Lower row (left to right): + +- **2** Not connected +- **4** Not connected +- **6** Not connected +- **8** RESET + +.. _emulate: https://www.arduino.cc/en/Tutorial/ArduinoISP +.. _firmware: https://github.com/mntmn/reform/reform-attiny-fw diff --git a/handbook/source/motherboard/reform-motherboard.png b/handbook/source/motherboard/reform-motherboard.png Binary files differ. diff --git a/handbook/source/motherboard/reform-power-ReformPower.png b/handbook/source/motherboard/reform-power-ReformPower.png Binary files differ. diff --git a/handbook/source/quickstart/index.rst b/handbook/source/quickstart/index.rst @@ -19,7 +19,7 @@ To log in, enter "root" as the username and "reform" as the password. From this console environment, you can: -- Format an mSATA SSD drive (if installed) and install an OS to it +- Format an mSATA SSD drive (if you put one in the mSATA slot) and install an OS to it - Secure the root account and create standard user accounts - Try some preinstalled graphical demos - Inspect or repair the system diff --git a/handbook/source/thermal/index.rst b/handbook/source/thermal/index.rst @@ -0,0 +1,28 @@ +Thermal +======= + +The main source of heat inside Reform is the i.MX6 SoC and its memory chips. Most of the heat goes into the blue passive heatsink that is glued to it. A fan which is mounted to the bottom plate then blows air over the heatsink into the direction of the ports, where it can escape through gaps in the case. + +The fan is needed to push hot air out of the case, preventing overheating of the system. Normally, its full power is only needed when the system is under heavy load, for example when the GPU (3D graphics processor) is very active or all 4 cores are busy compiling code. The fan should turn on to full power when the SoC temperature is over 65 degrees celcius. + +One of the three fan cables (yellow) connects to the PWM1 pin of the i.MX6. The fan's speed can be controlled via pulse width modulation. This is usually the job of the reformd script, which monitors the core temperature and sets the fan to full power when the temperature is over 65 degrees Celcius. + +To check the temperature of the system, you can use the command: + +.. code-block:: shell + + cat /sys/class/thermal/thermal_zone0/temp + +The following is an example of commands that reformd uses to change the fan speed (in this instance, to set it to 75%): + +.. code-block:: shell + + # make the first PWM device available + echo 0 > /sys/class/pwm/pwmchip1/export + # define what a full period is + echo 10000 > /sys/class/pwm/pwmchip1/pwm0/period + # set how much of this period should be in the "ON" state (75%) + echo 7500 > /sys/class/pwm/pwmchip1/pwm0/duty_cycle + # enable the PWM output + echo 1 > /sys/class/pwm/pwmchip1/pwm0/enable + diff --git a/handbook/source/trackball/index.rst b/handbook/source/trackball/index.rst @@ -0,0 +1,33 @@ +The Trackball +============= + +The trackball uses the same microcontroller and LUFA framework as the keyboard_, but instead of scanning a matrix of switches, it gets X and Y movement coordinates from the PMW3360DM-T2QU optical sensor that is connected via SPI. + +Wheel Mode, Middle Click +------------------------ + +The trackball firmware has a special "wheel mode" that allows you to use it like a mouse wheel for scrolling or to perform a middle mouse click. + +You can enter wheel mode by pressing the left button and then pressing the right button while keeping the left button pressed. Release both buttons. Rolling the ball up and down will send wheel up/down commands. Clicking the right button will perform a middle click. Clicking the left button will exit wheel mode. + +Firmware +-------- + +You can find the Reform trackball firmware_ in the source folder "reform-trackball-fw". + +The trackball firmware is based on the LUFA USB device library and implements a USB HID Mouse. To modify the behaviour of the trackball, edit the file Mouse.c and rebuild the firmware by typing the following command in a terminal: + +.. code-block:: shell + + make + +As with the keyboard, the trackball's MCU has to be in "Atmega DFU bootloader" USB mode. This is achieved by shorting the pins HWB and GND with a jumper and then briefly shorting the RESET pin to ground. The pins are marked on the silkscreen of the main trackball PCB. + +After a reset with HWB pulled to ground, The trackball will reappear as a Atmel DFU bootloader USB device. You can then upload your new firmware by executing: + +.. code-block:: shell + + ./flash.sh + +.. _firmware: https://github.com/mntmn/reform/reform-trackball-fw +.. _keyboard: ../keyboard/index.html
