Commit 8712fe7a authored by David Boddie's avatar David Boddie

Merge branch 'master' into 'hardware'

# Conflicts:
#   APIs.rst
parents f084f805 d5ea930f
......@@ -3,11 +3,17 @@
API Docs
========
This page lists phone/Librem-5 specific API documentation. For links
to upstream documentation check also :ref:`resources`. This list is
currently being `filled in
This chapter contains API documentation specific to the Librem 5 as well as
links to upstream documentation.
API documentation for the underlying GNOME platform can be found in
:ref:`gnome_resources`. This list is currently being `filled in
<https://source.puri.sm/Librem5/developer.puri.sm/issues/60>`_.
See also the :ref:`software_reference` for detailed information about the
Librem 5 software stack.
Phone/Messaging APIs
--------------------
* Modem/Sim card access is provided via the `ModemManager`_ DBBus APIs
......
......@@ -8,9 +8,13 @@ App Development
Apps/Constraints
Apps/Gnome
Apps/Kde
Apps/Design
Apps/PublishingApps
If you are interested in app development then you're in the right place! Here, you can find out how to make, build, deploy, and publish apps for distributing. Take a look at the flow charts below to get a visual idea of the layout of this apps section.
If you are interested in app development then you're in the right place! Here,
you can find out how to make, build, deploy, and publish apps for distributing.
Take a look at the flow charts below to get a visual idea of the layout of this
apps section.
|pic1| |pic2|
......@@ -29,7 +33,8 @@ First determine which phone environment you want to integrate with:
For more information, see :ref:`environments`.
Your environment will determine which tools and languages are available to you for app development.
Your environment will determine which tools and languages are available to you
for app development.
Next, what kind of application format would you like?
......@@ -44,8 +49,9 @@ You can follow the above charts to determine the IDE/build tool suggested.
* :ref:`qt` provides QtCreator and QtDesigner, good tools for designing Qt based UIs
* For building a deb package, `git-buildpackage <http://honk.sigxcpu.org/projects/git-buildpackage/manual-html/gbp.html>`_ is the preferred build method
Once your app is ready to be distributed to other developers, you can submit your app for inclusion.
Once your app is ready to be distributed to other developers, you can submit
your app for inclusion.
* There will be a flatpak repository for only free software flatpaks. This repository will be hosted by PureOS
* There will be a flatpak repository for only free software flatpaks. This
repository will be hosted by PureOS
* To submit your app for inclusion into Debian, follow `standard Debian package submission procedures <https://www.debian.org/doc/manuals/distribute-deb/distribute-deb.html#adding-packages-to-debian>`_
......@@ -34,7 +34,7 @@
GTK+
====
`GTK+ <GTK+ website_>`_ is the graphical application framework used to develop all GNOME applications. This section presents tips and tricks with GTK+ to help you develop great adaptive applications for GNOME, for general GTK+ and GNOME development resources please check the :ref:`resources` page.
`GTK+ <GTK+ website_>`_ is the graphical application framework used to develop all GNOME applications. This section presents tips and tricks with GTK+ to help you develop great adaptive applications for GNOME, for general GTK+ and GNOME development resources please check the :ref:`gnome_resources` page.
Don't forget to check its `documentation <GTK+ 3 documentation_>`_ out.
`libhandy <libhandy website_>`_ is a widget library for GTK+. It contains widgets useful for both phone applications and adaptive applications and it is going to be used in that page as an extension to GTK+.
......
......@@ -3,11 +3,14 @@
Introduction
=============
Apps for the Librem 5 will be typically built using the open source GTK+ toolkit. In fact many of the apps available will be ported from already existing GTK+ apps which are part of the GNOME environment. In your efforts to write an app or port a current app to the Librem 5, you are likely going to use GTK+ and the tooling around it for development.
Apps for the Librem 5 will be typically built using the open source GTK+
toolkit. In fact many of the apps available will be ported from already
existing GTK+ apps which are part of the GNOME environment. In your efforts to
write an app or port a current app to the Librem 5, you are likely going to use
GTK+ and the tooling around it for development.
*************************************
The tools
*************************************
The Tools
---------
- GNOME Builder
- flatpak, flatpak-builder (Your app package format)
......@@ -17,9 +20,8 @@ The tools
- GNOME environment (Librem 5 runs GNOME by default)
- libhandy (library with GTK+ widgets for mobile phones)
*************************************
The Workflow
*************************************
------------
A typical developer workflow will involve something of this sort:
......
.. _gnome_resources:
GTK+/GNOME Resources
====================
When developing an application for the GNOME environment running on a Librem 5
phone, the following resources may contain useful information and advice:
* `GNOME developer center <https://developer.gnome.org/>`_
* `Introducton to GObject <https://blogs.gnome.org/desrt/2012/02/26/a-gentle-introduction-to-gobject-construction/>`_
* `HowDoI things in GNOME <https://wiki.gnome.org/HowDoI/>`_
* `GNOME API Reference <https://developer.gnome.org/references>`_
......@@ -11,4 +11,4 @@ GNOME
GNOME/GBuilder
GNOME/Gtk+
GNOME/Glade
GNOME/Resources
.. _emulators:
Emulators
=========
.. toctree::
qemu
......@@ -3,55 +3,16 @@
Getting in Touch
================
It is common to receive questions like "Will the Librem 5 support _____?" or "Is anyone working on adding support for _____ because I want to help?"
If you have questions about anything regarding the Librem 5, we would really like to hear them from you and there are a couple of recommended ways to reach out:
There are a couple of ways to contact us and join the fun. We have email lists that are quiet now but will be lively once the dev kits have been sent out. We also have Matrix chat rooms where other volunteers hang out as well as many people from the Purism team. Both places are great locations to introduce yourself and ask questions.
.. _email-lists:
Email Lists
###########
Watch technical email regarding ongoing software development within the team and feel free to chime in with good suggestions. Depending on the level of involvement that you're seeking, you can sign up for any/all of these email lists where you can follow development and ask questions:
* `librem-5-announce@lists.community.puri.sm <https://lists.community.puri.sm/listinfo/librem-5-announce>`_ : General Librem 5 announcements (low volume, read only)
* `librem-5-dev@lists.community.puri.sm <https://lists.community.puri.sm/listinfo/librem-5-dev>`_ : For all sorts of development conversations. This list will be very technical in nature so join the fun!
* `librem-5-users@lists.community.puri.sm <https://lists.community.puri.sm/listinfo/librem-5-users>`_ : For general users of the Librem 5 that are not so interested in the nitty gritty technical details. This list will contain light traffic until the Librem 5 ships in January 2019.
* `all@lists.community.puri.sm <https://lists.community.puri.sm/listinfo/all>`_ : All announcements to all community members
For the mailing lists, there is no account setup required. Just subscribe, see a full list `here <https://lists.puri.sm/>`_.
.. _matrix-chat-rooms:
Matrix Chat Rooms
#################
Join our Matrix chat rooms using your Matrix login:
Librem 5 specific:
* `community/librem-5 <https://matrix.to/#/#community-librem-5:talk.puri.sm>`_ (ID: !BSqRHgvCtIsGittkBG:talk.puri.sm) : For Librem 5 development chatter
* `Phosh <https://matrix.to/#/#phosh:talk.puri.sm>`__ (ID: !CBfWYXjnVtAdBQWXVI:talk.puri.sm): For discussions regarding `phosh <https://source.puri.sm/Librem5/phosh>`__
* `Libhandy <https://matrix.to/#/#libhandy:talk.puri.sm>`__ (ID: !nrNOrVsRZxzaDdspgs:talk.puri.sm): For discussions regarding the `libhandy <https://source.puri.sm/Librem5/libhandy>`__ GTK+ library
* `Chatty <https://matrix.to/#/#chatty:talk.puri.sm>`__ (ID: !zaQzHCRfyTXoMIqcxq:talk.puri.sm): For discussions regarding the `chatty <https://source.puri.sm/Librem5/chatty>`__ messaging application
* `Calls <https://matrix.to/#/#calls:talk.puri.sm>`__ (ID: !ghzbolmVJyjKZTxyfl:talk.puri.sm): For discussions regarding the `calls <https://source.puri.sm/Librem5/calls>`__ application
Community rooms for non-Librem 5 discussions:
* `community/pureos <https://matrix.to/#/#community-pureos:talk.puri.sm>`_ (ID: !bGtSETqkYFOebMtlfH:talk.puri.sm) : For discussions around PureOS in general
* `community/purist <https://matrix.to/#/#community-purist:talk.puri.sm>`_ (ID: !RkGDRtKCBzjnWMEGMV:talk.puri.sm) : For Purist Services
* `community/general <https://matrix.to/#/#community-general:talk.puri.sm>`_ (ID: !aXWDJNTtEfhSXdPoQT:talk.puri.sm) : For questions that are not obviously related to the Librem 5, PureOS, or Purist Services
* `community/heads <https://matrix.to/#/#community-heads:talk.puri.sm>`_ (ID: !BSPqgzeiCeaSBayTLM:talk.puri.sm): For questions regarding HEADS
If you do not already have a Matrix account, please visit `Matrix's website <https://matrix.org>`_ to choose a Matrix client where you can register. Once you have a registered Matrix account, you should log into the default matrix.org server where you can search for our community Matrix rooms on our talk.puri.sm Matrix server.
Example: To find the community/librem-5 room, you should search for #community-librem-5:talk.puri.sm
If you have any issues finding our Matrix rooms, please email admins@puri.sm with your Matrix id and they will make sure you get invited to the rooms (although invitations are not necessary for access).
Once you have access to the Matrix channels, please say "Hi" and introduce yourself. Let us know who you are and what areas of development interest you the most so that we can guide you to the right resources for your development.
Code Repositories
#################
Our `code repos <https://source.puri.sm/>`_ are where anyone can register an account to view our repositories, create your own, file issues, and submit pull requests.
It is common to receive questions like "Will the Librem 5 support _____?" or
"Is anyone working on adding support for _____ because I want to help?"
The following sections contain all you need to know to get involved with the
Librem 5 project, from participating in discussions to submitting bug reports
and patches.
.. toctree::
Contact/Community
Contact/Volunteering
Contact/Contributing
Contact/Contributing/Translations
Contact/Issues
.. _community:
Community
=========
If you have questions about anything regarding the Librem 5, we would really
like to hear from you and there are a couple of recommended ways to contact us
and join the fun. We have email lists that are quiet now but will be lively
once the dev kits have been sent out. We also have Matrix chat rooms where
other volunteers hang out as well as many people from the Purism team. Both
places are great locations to introduce yourself and ask questions.
.. _email-lists:
Email Lists
-----------
Watch technical email regarding ongoing software development within the team
and feel free to chime in with good suggestions. Depending on the level of
involvement that you're seeking, you can sign up for any/all of these email
lists where you can follow development and ask questions:
* `librem-5-announce@lists.community.puri.sm <https://lists.community.puri.sm/listinfo/librem-5-announce>`_ : General Librem 5 announcements (low volume, read only)
* `librem-5-dev@lists.community.puri.sm <https://lists.community.puri.sm/listinfo/librem-5-dev>`_ : For all sorts of development conversations. This list will be very technical in nature so join the fun!
* `librem-5-users@lists.community.puri.sm <https://lists.community.puri.sm/listinfo/librem-5-users>`_ : For general users of the Librem 5 that are not so interested in the nitty gritty technical details. This list will contain light traffic until the Librem 5 ships in January 2019.
* `all@lists.community.puri.sm <https://lists.community.puri.sm/listinfo/all>`_ : All announcements to all community members
For the mailing lists, there is no account setup required. Just subscribe, see
a full list `here <https://lists.puri.sm/>`_.
.. _matrix-chat-rooms:
Matrix Chat Rooms
-----------------
Join our Matrix chat rooms using your Matrix login:
Librem 5 specific:
* `community/librem-5 <https://matrix.to/#/#community-librem-5:talk.puri.sm>`_ (ID: !BSqRHgvCtIsGittkBG:talk.puri.sm) : For Librem 5 development chatter
* `Phosh <https://matrix.to/#/#phosh:talk.puri.sm>`__ (ID: !CBfWYXjnVtAdBQWXVI:talk.puri.sm): For discussions regarding `phosh <https://source.puri.sm/Librem5/phosh>`__
* `Libhandy <https://matrix.to/#/#libhandy:talk.puri.sm>`__ (ID: !nrNOrVsRZxzaDdspgs:talk.puri.sm): For discussions regarding the `libhandy <https://source.puri.sm/Librem5/libhandy>`__ GTK+ library
* `Chatty <https://matrix.to/#/#chatty:talk.puri.sm>`__ (ID: !zaQzHCRfyTXoMIqcxq:talk.puri.sm): For discussions regarding the `chatty <https://source.puri.sm/Librem5/chatty>`__ messaging application
* `Calls <https://matrix.to/#/#calls:talk.puri.sm>`__ (ID: !ghzbolmVJyjKZTxyfl:talk.puri.sm): For discussions regarding the `calls <https://source.puri.sm/Librem5/calls>`__ application
Community rooms for non-Librem 5 discussions:
* `community/pureos <https://matrix.to/#/#community-pureos:talk.puri.sm>`_ (ID: !bGtSETqkYFOebMtlfH:talk.puri.sm) : For discussions around PureOS in general
* `community/purist <https://matrix.to/#/#community-purist:talk.puri.sm>`_ (ID: !RkGDRtKCBzjnWMEGMV:talk.puri.sm) : For Purist Services
* `community/general <https://matrix.to/#/#community-general:talk.puri.sm>`_ (ID: !aXWDJNTtEfhSXdPoQT:talk.puri.sm) : For questions that are not obviously related to the Librem 5, PureOS, or Purist Services
* `community/heads <https://matrix.to/#/#community-heads:talk.puri.sm>`_ (ID: !BSPqgzeiCeaSBayTLM:talk.puri.sm): For questions regarding HEADS
If you do not already have a Matrix account, please visit `Matrix's website
<https://matrix.org>`_ to choose a Matrix client where you can register. Once
you have a registered Matrix account, you should log into the default matrix.org
server where you can search for our community Matrix rooms on our talk.puri.sm
Matrix server.
Example: To find the community/librem-5 room, you should search for #community-librem-5:talk.puri.sm
If you have any issues finding our Matrix rooms, please email admins@puri.sm with your Matrix id and they will make sure you get invited to the rooms (although invitations are not necessary for access).
Once you have access to the Matrix channels, please say "Hi" and introduce yourself. Let us know who you are and what areas of development interest you the most so that we can guide you to the right resources for your development.
Code Repositories
-----------------
Our `code repos <https://source.puri.sm/>`_ are where anyone can register an account to view our repositories, create your own, file issues, and submit pull requests.
......@@ -3,11 +3,6 @@
Contributing
============
.. toctree::
:hidden:
Contributing/Translations
We welcome merge requests and issues being filed in our code repositories. Typically, issues get filed under the project that the issue relates to and you can browse our `list of projects <https://source.puri.sm/Librem5/>`_. For example, if you find an issue with the documentation, you can file an issue under the `developer docs <https://source.puri.sm/Librem5/developer.puri.sm/issues>`_ project. An issue can be any mistake you found in the project, e.g. a crash, a bug, or even a typo. You are welcome to file an issue when you want to make us aware of some important topic relating to the project as well.
Aside from project specific issues, we do have an `Apps_issues <https://source.puri.sm/Librem5/Apps_Issues>`_ project to track tasks like applications to port to the phone or issues with them. Here you can add a task for a particular app to be ported to the phone. However, be sure to search our `list of projects <https://source.puri.sm/Librem5/>`_ first before opening an issue under `Apps_issues <https://source.puri.sm/Librem5/Apps_Issues>`_.
......@@ -28,7 +23,7 @@ Repository Guidelines
If you have a repository that you maintain but expect others to contribute to, then it is helpful for newcomers to know who to contact when they have questions regarding that repository. For this reason, we would like every repository to contain a `doap <https://en.wikipedia.org/wiki/DOAP>`_ file with the maintaner field filled out. Optionally, if you know of someone that will regularly review your merge requests, then the helper field should also be completed. For a list of supported doap fields, see `this list on Wikipedia <https://en.wikipedia.org/wiki/DOAP>`_ but below is complete example you can modify to match your project:
.. literalinclude:: examples/doap.xml
.. literalinclude:: ../examples/doap.xml
:language: XML
Be sure to adapt the above template to match your project info.
......
.. _howto:
.. _volunteering:
Volunteering
============
Are you as excited about the Librem 5 phone as we are?! So excited you *NEED* to volunteer? Well we are excited to welcome you to a community of like minded people!
***************
The Common Goal
***************
---------------
Together, we want to improve PureOS for the Librem 5 and there are several ways in which you can help.
......@@ -22,9 +21,9 @@ Whether it be porting/writing apps, finding defects, writing tutorials, or anyth
Note: To include your app in PureOS, please see :ref:`Publishing-Apps`
**************************************
Getting your own puri.sm email account
**************************************
--------------------------------------
If you do not trust the common email providers such as Google, Hotmail, Yahoo, etc. and would like your own email address hosted by us, you can request an @community.puri.sm email account. Just send us an email: admins@puri.sm and we'll get you all setup with your @community.puri.sm email account. Be sure to include the following in your email:
* Full name
......
.. _development_environment:
Setting up a Development Environment
====================================
.. toctree::
Development_Environment/Requirements.rst
Development_Environment/Boards.rst
Development_Environment/Workstation.rst
.. _boards:
Development Kits
================
The development boards for the Librem 5 are built around the
`EmCraft i.MX 8M SoM <https://www.emcraft.com/products/868>`_, a development
platform based on the i.MX8 CPU.
It is possible to develop software for the Librem 5 without a development kit.
If you are developing applications that do not rely on specific features of the
phone, or that only need to be tested for use on a small screen, it can be
practical to :ref:`use an emulator <emulators>` to help with development.
Also take a look at the :ref:`mini-tutorials` page for some common
commands and some application setup that is not board specific.
.. toctree::
:maxdepth: 1
Boards/First-Steps
Boards/real-hardware
Boards/emulators
Boards/mini-tutorials
.. _emulators:
Emulators
=========
Many applications can be prototyped and tested using an emulator instead of
a development board. An emulator can provide an test environment that provides
some of the features and constraints of a hardware solution while remaining
convenient for application developers to use.
The following sections cover emulators that can be used to test applications
within the Librem 5 system environment and describe how to set them up on
different operating systems.
.. toctree::
qemu
.. _requirements:
Requirements
============
Software can be developed for the Librem 5 on a variety of systems and
platforms. Typically, the developer will be using a desktop or laptop computer
with sufficient resources to run a modern GNU/Linux distribution, such as
PureOS or Debian, and the GNOME desktop environment. This provides access to
the tools that are recommended for building applications for the Librem 5.
.. workstation:
Workstation
===========
Application development for the Librem 5 is not tied to a particular set of
technologies. However, for simplicity, we recommend that you use the same set
of tools and libraries that the Librem 5 developers have used.
* GNOME technologies: A run through the various GNOME technologies.
* GNOME Builder documentation: Documentation for the GNOME IDE.
* Meson: The recommended build system.
* Flatpak: Application sandboxing and distribution.
* gitg: The GNOME git client.
.. _hardware_ref:
Hardware Reference
==================
This chapter contains a description of the hardware included with the Librem 5
developer kit and phone. The following list is a placeholder that will be
replaced with individual sections. It is based on the information about the
developer kits contained in `this blog post <https://puri.sm/posts/librem5-2018-11-hardware-report/>`_.
* 10/100 Ethernet
* Audio Codec
* Bluetooth I2S interface
* Bluetooth (UART4)
* Camera (MIPI CSI)
* Charge Controller
* Charge controller's thermistor
* Display's LED backlight
* Earpiece speaker
* eMMC boot (boot mode switch in the "up" position)
* External microphone
* GNSS (UART interface and antenna)
* Haptic motor
* hardware kill switches for WiFi / BT and microphone
* headphones detect (HP_DET)
* Headphone speakers
* Headset microphone
* IMU (accelerometer, gyro, magnetometer)
* JTAG
* Microphone select IC
* Mini-HDMI
* MIPI DSI LCD panel
* On-board microphone
* Power indicator LEDs
* Powering from 18650 battery
* Proximity / ambient light sensor
* push buttons (power button, reset button, volume up, volume down)
* RedPine WiFi/BT M.2 module on SDIO
* RTC
* Safely charging an 18650 battery
* Serial Downloader (loading u-boot via USB)
* Smart card reader and smart card slot
* SoM (pinout mostly validated, SoC, eMMC, and PMIC working)
* SPI NOR Flash
* Touch controller
* UART Debug
* USB-C
* USB-C role switching
* USB Hub and SD controller
* User LED
* WLAN/BT antennae
* WWAN hardware kill switch
* WWAN I2S interface
* WWAN module, SIM card and antenna
Additional sections may also cover these components:
* Audio jacks - headphone, microphone
* Modem
.. _introduction:
Introduction
============
The Librem 5 will be an i.MX8 phone running PureOS, a Debian derivative. The
kernel will be the 4.18 mainline kernel with some additional drivers. For the
graphical windowing system, it will make use of a Wayland compositor together
with a shell named phosh. The graphical environment will be based on the GNOME
platform with a variety of modifications. Below you can find a diagram on the
overall software architecture stack.
.. image:: images/L5-stack.png
:width: 700px
:height: 500px
:align: center
.. toctree::
Introduction/History
.. _boards:
.. _history:
Development Boards
==================
History of the Librem5
======================
Developing a dev kit and eventually a phone is a long process that
requires many hardware iterations over time to test and determine
......@@ -12,7 +12,6 @@ are several metrics such as performance, freedom of the firmware
more that are taken into account when selecting hardware components
for the Librem 5 phone.
On the freedom front, we have been committed to the i.MX line of
CPUs as opposed to something less freedom respecting such as Intel
hardware. Since the i.MX8 CPU had not been released when the Librem
......@@ -27,15 +26,3 @@ available, the :ref:`Dev-kit` page will remain empty. However
once the dev kit *is* available, this is where you will find
complete information on the hardware and how to set up your dev
kit to start using it.
Also take a look at the :ref:`mini-tutorials` page for some common
commands and some application setup that is not board specific.
.. toctree::
:maxdepth: 1
Boards/First-Steps
Boards/real-hardware
Boards/emulators
Boards/mini-tutorials
.. index:: Software Reference
.. _software_reference:
Software Reference
==================
This chapter provides information about the software components used in the
Librem 5 stack and includes links to useful external resources.
.. toctree::
Software_Reference/Environments
Software_Reference/Wayland
.. index:: Development Resources
.. _resources:
Development Resources
=====================
This page provides links to useful external resources.
GTK+/GNOME
----------
When developing an application for GNOME or GTK+ or working on the shell these links might be useful:
* `GNOME developer center <https://developer.gnome.org/>`_
* `Introducton to GObject <https://blogs.gnome.org/desrt/2012/02/26/a-gentle-introduction-to-gobject-construction/>`_
* `HowDoI things in GNOME <https://wiki.gnome.org/HowDoI/>`_
.. _wayland:
Wayland
-------
=======
When working on the compositor these links might be useful:
* `Wayland architecture <https://wayland.freedesktop.org/architecture.html>`_
......
.. _volunteering:
Community
=========
.. toctree::
Volunteering/HowTo
Librem 5 Docs
=============
Librem 5 Developer Documentation
================================
.. image:: images/purism_logo.png
:width: 200px
:height: 55px
:align: right
*****
Intro
*****
Welcome to the Librem 5 documentation! This site contains instructions and examples to help you accomplish your goals with the Librem 5 dev kit and phone.
The Librem 5 will be an i.MX8 phone running PureOS, a Debian derivative. The kernel will be the 4.18 mainline kernel with some additional drivers. For the graphical windowing system, it will make use of a Wayland compositor together with a shell named phosh. The graphical environment will be based on the GNOME platform with a variety of modifications. Below you can find a diagram on the overall software architecture stack.
.. image:: images/L5-stack.png
:width: 700px
:height: 500px
:align: center
Welcome to the Librem 5 documentation! This site contains instructions and
examples to help you accomplish your goals with the Librem 5 dev kit and phone.
.. toctree::
:titlesonly:
......@@ -24,16 +15,13 @@ The Librem 5 will be an i.MX8 phone running PureOS, a Debian derivative. The ker
:caption: Table of Contents
:glob:
Boards
Environments
Introduction
Development_Environment
Apps
APIs
Design
Volunteering
Contributing
Resources
Contact
FAQ
Issues
Software_Reference
Hardware_Reference
Appendix
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