Difference between revisions of "PinePhone (Pro) Keyboard"

Jump to navigation Jump to search
(→‎Troubleshooting: More information)
(19 intermediate revisions by 7 users not shown)
Line 5: Line 5:
== Getting started ==
== Getting started ==
[[File:Ppkb_description.png|thumb|upright=1.2|
[[File:Ppkb_description.png|thumb|upright=1.2|
1. Pogo pins<br>
① Contact pads<br>
2. Battery switch<br>
Battery switch<br>
3. USB-C]]
USB-C connector]]


The keyboard case works with both the PinePhone and PinePhone Pro and features a clam-shell design. It uses pogo pins located on the phone’s midsection and attaches by replacing the default back cover. When folded, the phone’s screen and the keyboard rest securely against each other. The hinge features a 180° design, which not only allows for two-hand typing on a surface but also for comfortable thumb-typing when fully extended. The etched keycaps can be easily relocated for alternate layouts such as AZERTY or QWERTZ. The keyboard case runs an [https://xff.cz/git/pinephone-keyboard/ open firmware], which means that anyone with the know-how can alter existing functions or add new ones. The bottom (keyboard) and top (phone) sections of the assembly are well-balanced thanks to the large, 6000mAh, internal battery capable of charging the PinePhone (Pro) during operation. The internal battery effectively triples the phone’s battery life. The internal keyboard battery can be manually toggled on/off and the keyboard’s battery charge level can be read in the supported OSes; the keyboard remains functional with the battery fully depleted.
The keyboard case works with both the PinePhone and PinePhone Pro and features a clam-shell design. It uses pogo pins located on the phone’s midsection and attaches by replacing the default back cover. When folded, the phone’s screen and the keyboard rest securely against each other. The hinge features a 180° design, which not only allows for two-hand typing on a surface but also for comfortable thumb-typing when fully extended. The etched keycaps can be easily relocated for alternate layouts such as AZERTY or QWERTZ. The keyboard case runs an [https://xff.cz/git/pinephone-keyboard/ open firmware], which means that anyone with the know-how can alter existing functions or add new ones. The bottom (keyboard) and top (phone) sections of the assembly are well-balanced thanks to the large, 6000mAh, internal battery capable of charging the PinePhone (Pro) during operation. The internal battery effectively triples the phone’s battery life. The internal keyboard battery can be manually toggled on/off and the keyboard’s battery charge level can be read in the supported OSes; the keyboard remains functional with the battery fully depleted.


You do not lose access to the PinePhone (Pro)’s USB-C port, speaker, microphone, or any external features, such as volume and lock buttons, with the keyboard attached. There is also a cut-out for the camera, torch, and headphone jack. The USB-C port on the keyboard is capable of powering both the keyboard and PinePhone (Pro) simultaneously. This means that you can plug in a USB mouse, a USB-C dongle, or some other peripheral while the phone and keyboard’s internal battery charge (please see the [[PinePhone (Pro) Keyboard#Safety|safety]] section). Please keep in mind that the keyboard case transforms the PinePhone (Pro) into a PDA, which means that taking calls will likely prove awkward without a wired or wireless headset connected.
You do not lose access to the PinePhone (Pro)’s USB-C port, speaker, microphone, or any external features, such as volume and lock buttons, with the keyboard attached. There is also a cut-out for the camera, torch, and headphone jack. The USB-C port on the keyboard is capable of powering both the keyboard and PinePhone (Pro) simultaneously. This means that you can plug in a USB mouse, a USB-C dongle, or some other peripheral while the phone and keyboard’s internal battery charge ('''warning:''' it is highly advised to read the [[PinePhone (Pro) Keyboard#Safety|safety]] section prior doing this). Please keep in mind that the keyboard case transforms the PinePhone (Pro) into a PDA, which means that taking calls will likely prove awkward without a wired or wireless headset connected.


=== Mounting the keyboard ===
=== Mounting the keyboard ===
Line 23: Line 23:
The keyboard will function automatically once a PinePhone running a compatible operating system is mounted. For alterations to physical layout and firmware see the relevant sections respectively.
The keyboard will function automatically once a PinePhone running a compatible operating system is mounted. For alterations to physical layout and firmware see the relevant sections respectively.


The keyboard features an in-built 6000mAh battery. The battery can be turned ON/OFF using the button on the right leading edge of the keyboard ②. A short button press activates the internal battery while a long (15 seconds) press deactivates it. Compatible operating systems display both the PinePhone’s and keyboard’s battery status.
The keyboard features an in-built 6000mAh battery. The battery can be turned ON/OFF using the button on the right leading edge of the keyboard ②. A short button press activates the internal battery while a long (15 seconds) press or double press deactivates it. Compatible operating systems display both the PinePhone’s and keyboard’s battery status.


You should charge the PinePhone and the keyboard <u>only</u> using the USB-C ③ port on the keyboard. The keyboard’s USB-C port cannot be used for peripherals. The PinePhone’s USB-C port remains operational when mounted in the keyboard and can be used for data and peripherals.
You should charge the PinePhone and the keyboard <u>only</u> using the USB-C ③ port on the keyboard. The keyboard’s USB-C port cannot be used for peripherals. The PinePhone’s USB-C port remains operational when mounted in the keyboard and can be used for data and peripherals.


=== Troubleshooting ===
=== Troubleshooting ===
There are multiple possible issues user could face. It is recommend to check the following most common issues and their solutions and workarounds. <!-- === Missing support in the operating system === -->
There are multiple possible hardware issues users could face. It is recommend to check the following most common hardware issues and their solutions and workarounds.


==== Pogo pins not making proper contact ====
==== Pogo pins not making proper contact ====
Line 36: Line 36:
* Apply '''slight''' pressure in the upper mid of the PinePhone's backside until the plastic holder pin towards the upper middle of the keyboard cover, until an audible click can be heard.
* Apply '''slight''' pressure in the upper mid of the PinePhone's backside until the plastic holder pin towards the upper middle of the keyboard cover, until an audible click can be heard.
* Make sure the contacts and pogo pins are clean and the pogo pins can be slightly pressed individually.
* Make sure the contacts and pogo pins are clean and the pogo pins can be slightly pressed individually.
* If the above does not work, a shim under the keyboard's contacts might be required, as explained [https://xnux.eu/pinephone-keyboard/faq.html#ts FAQ troubleshooting section]. See also this [https://freiburg.social/system/media_attachments/files/107/684/243/421/870/279/original/a5e9c68ff3510ec8.jpeg photo of where to place the shim]
* If the above does not work, a shim under the keyboard's contacts might be required, as explained [https://xnux.eu/pinephone-keyboard/faq.html#ts FAQ troubleshooting section]. See also this [https://freiburg.social/system/media_attachments/files/107/684/243/421/870/279/original/a5e9c68ff3510ec8.jpeg photo of where to place the shim], or [https://www.youtube.com/watch?v=4ixPjz6SPIA this video].


==== Top row is less responsive ====
==== Top row is less responsive ====
The keys of the top row may be less responsive. The issue can be worked around by adding inserts to the underside of the top row key caps to decrease the travel distance. More details regarding the workaround can be found in the corresponding section of the FAQ page of the developer megi: https://xnux.eu/pinephone-keyboard/faq.html#ts
The keys of the top row may be less responsive. The issue can be worked around by adding inserts to the underside of the top row key caps to decrease the travel distance. More details regarding the workaround can be found in the corresponding section of the FAQ page of the developer megi: https://xnux.eu/pinephone-keyboard/faq.html#ts
==== Software issues ====
For any software issue please see the [[PinePhone (Pro) Keyboard#Software support|Software support section]] and the [[PinePhone (Pro) Keyboard#Frequently asked questions|FAQ section]].


== Safety ==
== Safety ==
Line 45: Line 48:


{{warning|1=Do NOT plug any power source into the phone USB-C port while the keyboard is attached. Doing so may result in damage or loss of the keyboard charging functionality.}}
{{warning|1=Do NOT plug any power source into the phone USB-C port while the keyboard is attached. Doing so may result in damage or loss of the keyboard charging functionality.}}
Users may block the USB-C port of the phone while the keyboard is connected, while the functionality of the phone's USB-C port is being looked into. See [https://fosstodon.org/web/@silverhax/107783280758831068 here] for an example by user ''Silver''.
{{warning|1=Do NOT lube the keyboard with GPL 205G0 switch grease. It can cause problems with the key responsiveness and tactility.}}
{{warning|1=Do NOT lube the keyboard with GPL 205G0 switch grease. It can cause problems with the key responsiveness and tactility.}}
{{hint|Only use mild isopropyl alcohol when wiping down the clamshell of the device. Stronger solutions may partially strip the coatings.}}
{{hint|Only use mild isopropyl alcohol when wiping down the clamshell of the device. Stronger solutions may partially strip the coatings.}}
Line 60: Line 66:
Virtual keyboards such as <i>squeekboard</i> are opening whenever a text field is selected.
Virtual keyboards such as <i>squeekboard</i> are opening whenever a text field is selected.


To disable this behavior under GNU/Linux running Phosh, you can run the following:  
To disable this behavior under Linux running '''Phosh''' you can change the corresponding settings under ''Settings'' > ''Accessibility'' > ''Screen Keyboard'' (see [https://forum.pine64.org/showthread.php?tid=15789&pid=105152 here]). The virtual keyboard can also be disabled temporarily for one session using:  


To disable the virtual keyboard: <code>gsettings set org.gnome.desktop.a11y.applications screen-keyboard-enabled false</code>
* To temporarily disable the virtual keyboard: <code>gsettings set org.gnome.desktop.a11y.applications screen-keyboard-enabled false</code>


To enable the virtual keyboard: <code>gsettings set org.gnome.desktop.a11y.applications screen-keyboard-enabled true</code>
* To temporarily enable the virtual keyboard: <code>gsettings set org.gnome.desktop.a11y.applications screen-keyboard-enabled true</code>


The virtual keyboard needs to be activated before removing the keyboard case again.
The virtual keyboard needs to be activated before removing the keyboard case again.
Under '''Plasma Mobile''' the keyboard can be disabled via a widget, see [https://forum.pine64.org/showthread.php?tid=14789&pid=105077#pid105077 here].
In '''Sxmo''' disabling the keyboard is not required, as the keyboard will only shown when the corresponding hotkey button is pressed.


== Keyboard layout ==
== Keyboard layout ==
The keyboard features a default layout (pictured below) created and agreed upon by the community. The keyboard layout can be altered using software as well as by physically repositioning keycaps. All keycaps, with the <u>exception</u> of space and return keys, can be easily and safely relocated for alternative layouts corresponding to software settings.
The keyboard features a default layout (pictured below) created and agreed upon by the community. The keyboard layout can be altered using software as well as by physically repositioning keycaps. All keycaps, with the <u>exception</u> of space and return keys, can be easily and safely relocated for alternative layouts corresponding to software settings.


<gallery mode="nolines" widths="800px" heights="400px">
<gallery mode="nolines" widths="500px" heights="400px">
Image:Ppkb_layout2.png|The keyboard layout how the keys were originally intended
Image:Ppkb_layout2.png|The keyboard layout how the keys were originally intended
</gallery>
</gallery>
Line 104: Line 114:


== Hardware ==
== Hardware ==
Detailed keyboard specifications including schematics can be found on our Wiki: https://wiki.pine64.org/wiki/PinePhoneKeyboard
Key hardware specifications:
Key hardware specifications:
* Dimensions (closed): 161 x 95 x 21.5mm
* Dimensions (closed): 161 x 95 x 25mm
* Weights (without / with PinePhone mounted): ~ 191 / ~391 grams
* Weights (without / with PinePhone mounted): ~ 191 / ~391 grams
* Number of keys: 54
* Number of keys: 54
Line 157: Line 165:
''' Can you open the keyboard and add extra functionality? '''<br>
''' Can you open the keyboard and add extra functionality? '''<br>
It is possible to do so, however the production units can be extremely difficult to open. Do not attempt to open the keyboard if you do not want to risk cosmetic damage (scaring and scratching of the plastic).
It is possible to do so, however the production units can be extremely difficult to open. Do not attempt to open the keyboard if you do not want to risk cosmetic damage (scaring and scratching of the plastic).
''' How can I rotate the screen display in tty ? '''<br>
Under Linux this can be done using the command <code>echo 1 | sudo tee /sys/class/graphics/fbcon/rotate</code>
''' Top row stopped displaying symbols! (kernel > 5.17) ''' <br>
* For Phosh (at the example of Mobian) see: https://wiki.mobian-project.org/doku.php?id=ppaccessories
* For TTY and SWMO see: https://codeberg.org/HazardChem/PinePhone_Keyboard


== Documents ==
== Documents ==
Moderator
1,489

edits

Navigation menu