Commit 13c9ae12 authored by minute's avatar minute
Browse files

add a bunch of callouts/illustrations and missing content

parent 9b36dbeb
......@@ -57,6 +57,13 @@ U-Boot is a mini operating system and shell that allows you to inspect parts of
U-Boot itself has to be compiled with the board support files for Reform. This is done by the ``mkuboot.sh`` script that is part of the ``reform-system-image`` repository. The resulting file, processed to be in the correct format loadable by the i.MX8MQ processor is ``flash.bin``. This file has to be written to the boot medium at an offset of 33kB (33792 bytes).
The build process combines the following files into ``flash.bin``:
- Synopsys DDR4 controller calibration firmware ``lpddr4_pmu_train_*.bin`` (no source available)
- Cadence HDMI controller firmare ``signed_hdmi_imx8m.bin`` (no source available, optional)
- ARM trusted firmware "TF-A" ``bl31-iMX8MQ.bin`` (open source)
- The u-boot binary (open source)
U-Boot needs 2 files to boot Linux:
- The Linux kernel itself, named ``Image``.
......@@ -86,8 +93,6 @@ The Linux kernel parameters are passed via the ``bootargs`` U-Boot environment v
This tells the kernel to mount the root filesystem from the ``mmcblk1p1`` device, which is the first partition on the SD card. To boot from the second partition, for example, you would change this to ``mmcblk1p2``. ``mmcblk0...`` is the eMMC flash. ``ttymxc0`` is the serial UART SER1. ``cma=512M`` sets up a memory area for contiguous allocation for the GPU. ``pci=nomsi`` turns off message-signaled interrupts (MSI) for the PCIe controller, which helps with some WiFi cards.
TODO: mention ARM TF-A, DDR4 blob, HDMI blob
Operating System on NVMe
------------------------
......@@ -123,4 +128,4 @@ To let Linux load your root filesystem from your encrypted disk, you need a way
saveenv
boot
TODO: Provide an easier/automated way of doing this.
TODO: Provide an easier/automated way of copying the system to SSD.
Credits
=======
TODO: some people are still missing from special thanks!
TODO: rewrite/split thanks
:Concept, Electronics, Firmware, Software: Lukas F. Hartmann
......
......@@ -13,6 +13,17 @@ The biggest difference is the split spacebar: instead of one long key, there are
This makes the use of Ctrl key combinations more ergonomic. Next to the Ctrl key is a key with 3 dots (an ellipsis). This is normally the Menu key, but on the default MNT Reform system software, it is mapped to Compose (a key that allows you to generate Unicode symbols from Compose sequences). Lastly, MNT Reform features an additional modifier key, the Hyper key, in the lower left. The idea is to let you assign this key to whatever function you require.
OLED Menu
---------
.. image:: _static/illustrations/oled1-callouts.png
The keyboard has a built-in OLED display for interaction with the System Controller on the motherboard. You can select a menu option and scroll through the menu by using the **↑** and **↓** keys. To trigger the highlighted option, press **Enter**. Alternatively, you can press the shortcut key that is displayed on the right hand side of each menu option. For example, to show the Battery Status, press **B** when the menu is active. To leave the menu, press **ESC**.
.. image:: _static/illustrations/oled2-callouts.png
You can see detailled battery information including the estimated total charge percentage on the Battery Status screen reachable through the OLED menu. Each cell icon corresponds to one of the eight battery cells. The leftmost group of four icons represent the battery pack on the left side of the device, and the top icon in each group represents the leftmost cell in each pack -- assuming you look at MNT Reform when flipped on its back and the battery closer towards you.
Trackball
---------
.. image:: _static/illustrations/6t-callouts.png
......
......@@ -111,7 +111,7 @@ It accepts commands in the form of a single letter followed by return. A command
- *s*: Get System Controller state (a message string)
- *g*: Get estimated "fuel gauge" of batteries (percentage)
The individual cell voltages are measured by the Battery Monitor LTC6803IG-4#PBF and reported via SPI to the System Controller. The total voltage and current are measured by the INA260 chip and reported via I2C.
The individual cell voltages are measured by the Battery Monitor LTC6803IG-4#PBF and reported via SPI to the System Controller. The total voltage and current are measured by the INA260 chip and reported via I²C.
To understand the available commands in more detail, you can take a look at the System Controller's ``handle_commands()`` function.
......@@ -124,22 +124,21 @@ The System Controller is permanently connected to the main processor's UART2 (``
Flashing the Firmware
---------------------
.. image:: _static/illustrations/27t.png
.. image:: _static/illustrations/27-callouts.png
TODO: callouts for micro-usb and switches
You can find the source code of the firmware_ in the folder "reform2-lpc-fw" of the Reform source repository.
To flash the firmware of the System Controller, you need another computer and a Micro-USB cable.
1. Set DIP switch LPCPROG to "ON"
2. Press button LPCRESET
3. Connect Micro-USB cable
4. System Controller's memory appears as virtual flash drive on secondary computer
5. Execute `flash.sh` and provide path to virtual flash drive
TODO: Programming task: automatically find correct drive in flash script
6. Unplug cable
7. Set DIP switch LPCPROG to "OFF"
8. Press button LPCRESET
1. Set DIP switch LPCPROG to "ON".
2. Press button LPCRESET.
3. Connect Micro-USB cable.
4. System Controller's memory appears as virtual flash drive on secondary computer (check ``lsblk``).
5. Edit ``flash.sh`` and change the path to virtual flash drive (i.e. ``/dev/sdx``). **Make sure the path is correct, or you could destroy data on your harddisk!**
5. Execute ``flash.sh`` as ``root``.
6. Unplug Micro-USB cable.
7. Set DIP switch LPCPROG to "OFF".
8. Press button LPCRESET.
.. _firmware: https://source.mntmn.com/MNT/reform/reform2-lpc-fw
.. _handle_commands: https://source.mntmn.com/MNT/reform/reform2-lpc-fw/src/boards/reform2.c
......@@ -147,9 +146,8 @@ To flash the firmware of the System Controller, you need another computer and a
Expansion Port
--------------
.. image:: _static/illustrations/28t.png
.. image:: _static/illustrations/28-callouts.png
TODO: annotate expansion port and LPC
The Expansion Port U18, labelled "Hack the Planet" is meant for advanced users that want to connect sensors or other peripherals to MNT Reform's system controller. Please note that changing the system controller's program can disrupt the battery charging control loop, potentially causing over- or undercharged cells, resulting in physical damage and/or injury. **Experiment with the system controller only if you know exactly what you're doing and at your own risk.**
The Expansion Port features an SPI interface, two analog-digital converters, a UART, JTAG and 3.3V Power. All non-power pins can alternatively be used as GPIOs.
......@@ -243,7 +241,7 @@ To modify the scancodes of the keyboard matrix, edit the file Keyboard.c and reb
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.
To be able to flash the firmware to the keyboard, the ATMega has to be in a special mode where it identifies as an "Atmel DFU bootloader" USB device.
Remove the keyboard's frame and toggle the programming DIP switch SW84 on the keyboard to "ON". Then press the reset button SW83. Before doing this, you need a means to start the flashing command without MNT Reform's internal keyboard. You can use an external USB keyboard, or use the trackball/trackpad to copy and paste the flash command and a new line.
......@@ -256,14 +254,14 @@ The keyboard will reappear as a Atmel DFU bootloader USB device. You can then up
Backlight
---------
Most keys have a white light emitting diode (LED) to illuminate the transparent part of the keycaps, making the laser engraved letters visible in darkness. You can control the backlight's brightness via Circle key combinations or the OLED menu. (TODO: cross ref)
Most keys have a white light emitting diode (LED) to illuminate the transparent part of the keycaps, making the laser engraved letters visible in darkness. You can control the backlight's brightness via Circle key combinations or the OLED menu.
Replacing a Keycap
------------------
.. image:: _static/illustrations/22t.png
MNT Reform comes with custom MBK keycaps by MKTN, but you can use any keycaps compatible with Kailh Choc keyswitches. You can easily pull out individual keycaps with your fingernails or better, using a keycap puller, and swap them around. The only two keycap sizes on the keyboard are 1U and 1.5U.
MNT Reform comes with custom "MBK" keycaps by FKcaps, but you can use any keycaps compatible with Kailh Choc keyswitches. You can easily pull out individual keycaps with your fingernails or better, using a keycap puller, and swap them around. The only two keycap sizes on the keyboard are 1U and 1.5U.
Replacing a Keyswitch
---------------------
......@@ -275,26 +273,26 @@ Use a soldering iron and solder wick to remove the solder of one pin. Try to pul
.. _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
OLED Display
============
OLED Module
===========
TODO: describe OLED functionality (this has a lot of cross links to System Controller, because the OLED together with the keyboard's Circle key is the front end to the System Controller).
.. image:: _static/illustrations/21-callouts.png
TODO: OLED module illustration
TODO: "screenshot" of OLED menu
TODO: "screenshot" of battery mgmt screen
The OLED display sits on the OLED Module which is connected to the keyboard through a 4-pin, 1mm pitch flex cable. The communication protocol is I²C. The module is mounted in the Main Box on top of the keyboardd with two M2x6 flathead screws.
Trackball
=========
.. image:: _static/illustrations/7t.png
TODO: callouts, screws are in random places
TODO: fix 2 cap screws in illustration
The trackball uses the same microcontroller and LUFA library as the keyboard, but instead of scanning a matrix of switches, it gets X and Y movement coordinates from the PAT9125EL optical sensor that is connected via I2C. The electronic connection between trackball sensor and controller is made with a 6-pin 0.5mm pitch flex cable.
The trackball uses the same microcontroller and LUFA library as the keyboard, but instead of scanning a matrix of switches, it gets X and Y movement coordinates from the PAT9125EL optical sensor that is connected via I²C. The electronic connection between trackball sensor and controller is made with a 6-pin 0.5mm pitch flex cable.
The trackball has five buttons. These make use of the same keyswitches as the keyboard: Kailh Choc Brown (CPG135001D02). The button caps are 3D printed using SLA technology (Formlabs Form 2). If you want to substitute your own replacements, you can find the STL files for the caps in the MNT Reform source repository. The cup and lid of the trackball are 3D printed using the same method.
.. image:: _static/illustrations/8-1-callouts.png
Trackball Cleaning
------------------
......@@ -324,28 +322,24 @@ Trackpad
.. image:: _static/illustrations/8t.png
TODO: trackpad callouts
The trackpad uses the same microcontroller as the keyboard and trackball.
The trackpad uses the same microcontroller as the keyboard and trackball. To sense the touch and motion of fingers, it integrates an Azoteq TPS65-201 capacitive sensor which reports coordinates to the microcontroller via the SPI protocol.
TODO: describe Azoteq captouch sensor
.. image:: _static/illustrations/8-2-callouts.png
Trackpad Firmware
-----------------
You can find the trackpad firmware `in the source folder "reform2-trackpad-fw" <https://source.mnt.re/reform/reform/reform2-trackpad-fw>`_.
The trackpad firmware is based on the LUFA USB device library and implements a USB HID Mouse. To modify the behaviour of the trackpad, edit the file Mouse.c and rebuild the firmware by typing the following command in a terminal:
Same as the trackball and keyboard, the trackpad firmware is based on the LUFA USB device library and implements a USB HID Mouse. To modify the behaviour of the trackpad, edit the file Mouse.c and rebuild the firmware by typing the following command in a terminal:
.. code-block:: none
make
For flashing, the MCU has to be in "Atmega DFU bootloader" USB mode.
For flashing, the MCU has to be in bootloader USB mode. Toggle the programming DIP switch SW7 to "ON" and press the reset button SW6.
Toggle the programming DIP switch SW7 to "ON" and press the reset button SW6.
The trackpad will reappear as a Atmel DFU bootloader USB device. You can then upload your new firmware by executing:
The trackpad will reappear as an "Atmel DFU bootloader USB" device. You can then upload your new firmware by executing:
.. code-block:: none
......@@ -366,9 +360,7 @@ When working with MNT Reform internals, it is good practice to remove all batter
LiFePO4 cells are safely discharged to 2.5V. Please make sure not to discharge the cells further. If you plan to leave your MNT Reform turned off/uncharged for more than a few days, disconnect the battery packs or take out the cells to avoid deep discharge.
.. image:: _static/illustrations/13t.png
TODO: mark plus/minus poles
.. image:: _static/illustrations/13-callouts.png
Compatible Battery Cells
-------------------------
......
......@@ -18,7 +18,7 @@ Step 2: Turn On
First, insert the included SD card into the slot on the left hand side of the device.
Then, to turn Reform on, press **Circle** and then **1**. The **Circle** key is used for system control commands. When you press **Circle**, a menu of system control functions and their shortcuts will be displayed on the OLED screen embedded in the keyboard. **1** is the shortcut for turning the system power on. Alternatively you can scroll through the menu by using the **↑** and **↓** keys and trigger the highlighted option by pressing **Enter**.
Then, to turn Reform on, press **Circle** and then **1**. The **Circle** key is used for system control commands. When you press **Circle**, a menu of system control functions and their shortcuts will be displayed on the OLED screen embedded in the keyboard. **1** is the shortcut for turning the system power on.
Step 3: Log In
--------------
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment