PINE64 - User contributions [en]

PineTime Development

2021-04-10T15:05:17Z

Electr0lyte: /* Available firmware and projects */

== Reprogramming ==

[[PineTime devkit wiring|Wire it up]] and then [[Reprogramming the PineTime| flash something]].

== Available firmware and projects ==
{| class="wikitable"
!
! Project Homepage
! Project Source
! PineTime Implementations

|-
! FreeRTOS
|https://www.freertos.org
| https://sourceforge.net/projects/freertos/
|
{|
|[[InfiniTime]] (GitHub: [https://github.com/JF002/Pinetime JF002/Pinetime])
|-
|[https://github.com/kaythe/pinetime-os kaythe/pinetime-os]
|}

|-
! Zephyr
| https://www.zephyrproject.org
| https://github.com/zephyrproject-rtos/zephyr
|
{|
|[https://github.com/najnesnaj/pinetime-zephyr najnesnaj/pinetime-zephyr]
|-
|[https://github.com/SuperPrower/pinetime_zephyr_sample_fw SuperPrower/pinetime_zephyr_sample_fw]
|-
|[https://github.com/Dejvino/pinetime-hermes-firmware Dejvino/pinetime-hermes-firmware]
|-
|[https://github.com/endian-albin/pinetime-hypnos endian-albin/pinetime-hypnos]
|}

|-
! mynewt
| https://mynewt.apache.org/about/
| https://github.com/apache/mynewt-core
|
{|
|[https://github.com/lupyuen/pinetime-rust-mynewt lupyuen/pinetime-rust-mynewt]
|-
|[https://gitlab.com/caspermeijn/klok caspermeijn/klok]
|}

|-
! MbedOS
| https://os.mbed.com
| https://github.com/ARMmbed/mbed-os
|
{|
|[https://github.com/sethitow/mbed-pinetime sethitow/mbed-pinetime]
|-
|[https://github.com/geoffrey-vl/mbed-pinetime geoffrey.vl/mbed-pinetime]
|}

|-
! RIOT
| http://riot-os.org/
| https://github.com/RIOT-OS/RIOT/
| [https://github.com/bosmoment/PineTime-apps bosmoment/PineTime-apps]

|-
! TinyGo
| https://tinygo.org
| https://github.com/tinygo-org/tinygo
| [https://github.com/aykevl/go-smartwatch aykevl/go-smartwatch]

|-
! wasp-os (MicroPython)
| https://wasp-os.readthedocs.io/
| https://github.com/daniel-thompson/wasp-os
| [https://wasp-os.readthedocs.io/en/latest/install.html#pine64-pinetime-developer-edition WaspOS PineTime install guide]

|-
! wasp-os Companion app for Linux
| [https://gitlab.com/arteeh/wasp-companion arteeh/wasp-companion]
|
|

|-
! Rust + RTFM
| https://rtfm.rs/
| [https://github.com/rtfm-rs/cortex-m-rtfm rtfm-rs/cortex-m-rtfm]
| https://github.com/dbrgn/pinetime-rtfm/

|-
! Bare Metal
|
|
{|
|https://github.com/xriss/timecake
|-
|https://github.com/Arc13/Pyrus
|}
|
{|
|[https://github.com/xriss/timecake xriss/timecake]
|-
|[https://github.com/Arc13/Pyrus Arc13/Pyrus]
|}

|-
! AdaFruit bootloader
|
| https://github.com/adafruit/Adafruit_nRF52_Bootloader
| [https://github.com/daniel-thompson/wasp-bootloader daniel-thompson/wasp-bootloader]

|-
! Useful drivers
|
| https://github.com/sethitow/mbed-pinetime
| [https://github.com/sethitow/mbed-pinetime/tree/master/drivers https://github.com/sethitow/mbed-pinetime]

|-
! UI concepts and drawings
| [https://gitlab.com/arteeh/pinetime-os arteeh/pinetime-os]
|
|

|-
! Flashing app for Linux
| [https://gitlab.com/arteeh/pinetime-flasher arteeh/pinetime-flasher]
[https://github.com/alexr4535/siglo alexr4535/siglo]
|
|

|-
! Android companion app
| https://gadgetbridge.org/
| https://codeberg.org/Freeyourgadget/Gadgetbridge
| [https://github.com/JF002/Pinetime InfiniTime] [https://codeberg.org/Freeyourgadget/Gadgetbridge/commit/9b8f4d329e49cafdfe0497ed38a715faa9f844c6 initial support added]

|-
! Arduino
| https://youtu.be/4aFDjymXjOw
| https://github.com/atc1441/ATCwatch
| https://github.com/atc1441/ATCwatch

|-
! OTA Update Flasher / DaFlasher
| https://youtu.be/gUVEz-pxhgg
| https://github.com/atc1441/DaFlasherFiles
| https://github.com/atc1441/DaFlasherFiles

|-
! Flashing app for Windows
| [https://github.com/ZephyrLabs/PinetimeFlasher ZephyrLabs/PinetimeFlasher]
|
|

|-
|}

=== Manuals ===

* [https://github.com/JF002/Pinetime InfiniTime installation]
* [https://github.com/najnesnaj/pinetime-zephyr Zephyr installation] Beginner manual which explains how to install Zephyr (by najnesnaj).
* [https://wasp-os.readthedocs.io/en/latest/ Wasp-OS installation] Full manual with install instructions and an application writer's guide.

== How to write battery friendly software? ==

The key to save battery is to enable only what you need when you need it. nRF52832 has a lot of functionalities allowing you to draw as little current as possible. Here are some tips and tricks:

* Disable / shutdown / put in sleep mode '''all devices around the MCU''' (display controller, touch controller, external memory,...).
* Disable all '''peripheral inside the MCU''' when you don't need them (SPI, TWI(I²C),...). The power management of the NRF52832 is very smart and will completely shut down (power off and disable the clock) the peripheral when the software disables it.
* Put the MCU to sleep as soon and as often as possible. If you are not using a RTOS, this is done by calling ''WFE'' (wait for event) instruction. Most of the time, RTOS implement this functionality. For example, FreeRTOS calls it the ''tickless mode'' : it puts the CPU in sleep mode when no task is planned for execution for more than a specified time, and wakes up as soon as an event is detected or when a task is ready to run.
* Do not use logging (JLink RTT, SWO, semihosting,...), it uses a lot of power.
* Ensure that the debug circuitry of the MCU is not enabled when you measuring the battery life. The debug peripheral is enabled as soon as you connect a debugger to the device, and '''is not automatically disabled''', even if you disconnect the debugger you will have to wait for the battery to go flat to disable to port. The software running in the NRF52832 cannot disable the debug peripheral. How to disable the debug circuitry:
- using ''nrfjprog --reset''
- using JLinkExe : issue the command ''writeDP 1 0''

or with OpenOCD
- issue the command ''halt''
- issue the command ''flash fillw 0x10001208 0xFFFFFF00 0x01''
- issue the command ''reset''

you can check if the debug port is enabled using the following code
DWT->CYCCNT ? "NO":"YES"
* Read [https://infocenter.nordicsemi.com/pdf/nRF52832_Rev_2_Errata_v1.1.pdf the errata sheet of the MCU] and apply workarounds if they apply to your software.

== Wishlist ==

In order to keep track of features and changes to the hardware people would like to see, check out this article: [[PineTime Hardware Wishlist]]

== Compatibility with other projects ==

Different firmware running using different bootloaders and Bluetooth stacks on the nRF52832 have different requirements on how they should be initialised and what should be placed where in the internal flash.

To keep track of what, how and why things work like they do across the different projects, check out the [[PineTime SD MCUBoot|PineTime SoftDevice and MCUBoot compatibility]] article.

== Compatibility with companions apps and Bluetooth communication ==

There are a lot of different firmware running on the Pinetime that implement different BLE APIs (time synchronization, notifications, ...). Companion apps must be able to differentiate between different firmware and forks of the same firmware. See [[PineTime Bluetooth]].

== PineTime equivalents and jailbreaking ==

This page contains a list of PineTime-like smartwatches that might be "jailbreakable" or a good source for ideas for the PineTime: [[PineTime Equivalents]]

[[Category:PineTime]]

PineTime

2021-01-08T06:12:52Z

Electr0lyte: link the watch face repository to main page

== Frequently asked questions ==

'''Read these first!'''

* [[Frequently asked questions about the PineTime| Frequently Asked Questions about the devkit]]
* [[Reprogramming the PineTime|Reprogramming the PineTime (development kit)]]

== Default OS ==

The current default operating system on the PineTime is called [[InfiniTime]], you can find more information about the firmware on its GitHub page. First devkits shipped with a proprietary custom firmware.

== Short overview ==
'''Dimensions:''' 37.5 x 40 x 11mm 
'''Weight:''' 38 grams 
'''IP Rating:''' IP67 (waterproof to 1 meter (sealed edition!)) 
'''Display:'''
: '''Size:''' 1.3 inches (33mm) diagonal
: '''Type:''' IPS capacitive touchscreen, RGB 65K colors
: '''Display Controller:''' ST7789
: '''Resolution:''' 240x240 pixels 
'''System on Chip:''' Nordic Semiconductor nRF52832 
'''Flash:''' 512KB with additional 4MB SPI NOR 
'''RAM:''' 64KB 
'''Bluetooth:''' [[PineTime_Bluetooth|5.0 (including Bluetooth Low Energy)]] 
'''Sensors:''' Accelerometer, Heart rate sensor 
'''Feedback:''' Vibration motor 
'''Battery:''' 170-180mAh LiPo

= Community =
* [https://forum.pine64.org/forumdisplay.php?fid=134 PineTime forum]
* [https://app.element.io/#/room/#pinetime:matrix.org Matrix Channel] (No login required to read)
* IRC Server: [ircs://irc.pine64.org#pinetime irc.pine64.org] Channel: PineTime
* [https://t.me/pinetime Telegram group]
* [https://discordapp.com/invite/DgB7kzr Discord server invite link]

== Development efforts ==

To read more about development on the PineTime, the projects available and more technical details, check out [[PineTime Development]]

== Useful articles and blog posts ==

If you want to dive in to the ecosystem, here's a short list of various articles and blog posts that can help you set up your soft- or hardware development environment.

* [https://medium.com/swlh/sneak-peek-of-pinetime-smart-watch-and-why-its-perfect-for-teaching-iot-81b74161c159 Sneak Peek of PineTime Smart Watch… And why it’s perfect for teaching IoT]

* [https://medium.com/@ly.lee/building-a-rust-driver-for-pinetimes-touch-controller-cbc1a5d5d3e9 Building a Rust Driver for PineTime’s Touch Controller]

* [https://medium.com/@ly.lee/porting-druid-rust-widgets-to-pinetime-smart-watch-7e1d5a5d977a Porting (druid) Rust Widgets to PineTime Smart Watch]

* [https://medium.com/@ly.lee/optimising-pinetimes-display-driver-with-rust-and-mynewt-3ba269ea2f5c Optimising PineTime’s Display Driver with Rust and Mynewt]

* [https://www.zephyrproject.org/getting-started-with-zephyr-rtos-on-nordic-nrf52832-hackable/ Getting Started with Zephyr RTOS on Nordic nRF52832 hackaBLE]

* [https://blog.aegrel.ee/absniffer-cmsis-dap-sniffer.html Removing the lock and installing another firmware on the nRF52832 using CMSIS-DAP dongle on Linux]

* [https://github.com/JF002/nrf52-baseproject/wiki/Build,-program-and-debug-NRF52-project-with-JLink,-CMake-and-CLion Build, program and debug NRF52 project with JLink, CMake and CLion]

* [https://www.nrbtech.io/blog/2020/1/4/using-clion-for-nordic-nrf52-projects Using CLion for Nordic nRF52 projects]

* [https://dev.to/aaronc81/flashing-your-pinetime-using-an-st-link-and-openocd-54dd Flashing your PineTime using an ST-Link and OpenOCD]

* [https://zephyrlabs.github.io/Watchfaces/ Zephyrlabs: just a bunch of watchfaces made for the pinetime]

== Hardware ==

=== Display ===

Note: The factory-default software on the PineTime does not auto-detect the display being disconnected when it has already booted. That can cause garbled output, to fix it just restart the PineTime.

The display is driven using the ST7789 display controller. Use the following pins to drive the screen:

{| class="wikitable"
|-
! PineTime pin
! ST7789 pin
|-
| LCD_SCK (P0.02)
| SPI clock
|-
| LCD_SDI (P0.03)
| SPI MOSI
|-
| LCD_RS (P0.18)
| Command/Data pin (CD)
|-
| LCD_CS (P0.25)
| Chip select
|-
| LCD_RESET (P0.26)
| Display reset
|-
| LCD_BACKLIGHT_{LOW,MID,HIGH}
| Backlight (active low)
|}

Notes:

* Chip select must be held low while driving the display. It must be high when using other SPI devices on the same bus (such as external flash storage) so that the display controller won't respond to the wrong commands.
* SPI must be used in mode 3. Mode 0 (the default) won't work.
* LCD_DISPLAY_* is used to enable the backlight. Set at least one to low to see anything on the screen.
* Use SPI at 8MHz (the fastest clock available on the nRF52832) because otherwise refreshing will be super slow.

'''References''':

[https://github.com/adafruit/Adafruit-ST7735-Library/ Adafruit ST7789 driver in cpp]

=== Battery measurement ===

Reading whether the PineTime has power attached is easy: simply read the charge indication pin (P0.12). When it is high it is running on battery, when it is low it is charging.

Reading the battery voltage is a bit harder. For that you can use the battery voltage pin on P0.31 (AIN7). The returned value is 12 bits, which means it is 0..4095. You can get the measured voltage with the following formula, assuming a reference voltage of 3.3V (this is configurable in the ADC):

adcVoltage = adcValue / (4095 / 3.3)

The measured voltage is actually half of the actual battery voltage, because the ADC is connected between a voltage divider where both resistors are 1MΩ. This can be corrected by multiplying the value:

batteryVoltage = adcValue * 2 / (4095 / 3.3)

It's often better to avoid floating point values on embedded systems and in this case there is no reason to use float at all, we can just represent the value in millivolts. Therefore the formula can be simplified to:

batteryVoltage = adcValue * 2000 / (4095 / 3.3)
batteryVoltage = adcValue * 2000 / 1241

Converting this voltage to an estimated capacity in percent requires a more complicated algorithm, because Lithium-ion batteries have a non-linear discharge curve.

=== Button ===

The button on the side of the PineTime is disabled by default. To enable it, drive the button out pin (P0.15) high.

While enabled, the button in pin (P0.13) will be high when the button is pressed, and low when it is not pressed.

=== Touch panel ===

The touch panel is controlled by a Hynitron CST816S chips. Unfortunately, there is not much information about this chip on the internet apart from the datasheet below and a [https://github.com/lupyuen/hynitron_i2c_cst0xxse/ reference driver]. This is enough to implement a basic driver, but crucial information needed to implement advanced functionalities are missing (I²C protocol and registers, timings, power modes,...).

==== Pins ====

* P0.10 : Reset
* P0.28 : Interrupt (signal to the CPU when a touch event is detected)
* P0.06 : I²C SDA
* P0.07 : I²C SCL

==== I²C ====

* Device address : 0x15
* Frequency : from 10Khz to 400Khz

'''NOTE : ''' The controller go to sleep when no event is detected. In sleep mode, the controller does not communicate on the I²C bus (it appears disconnected). So, for the communication to work, you need to tap on the screen so that the chip wakes-up.

==== Touch events ====

Touch information is available from the 63 first registers of the controller. Remember: the device is in sleep mode when no touch event is detected. It means that you can read the register only when the touch controller detected an event. You can use the ''Interrupt'' pin to detect such event in the software.

These 63 bytes contain up to 10 touch point (X, Y, event type, pressure,...) :

{| class="wikitable"
! Byte
! Bit7
! Bit6
! Bit5
! Bit4
! Bit3
! Bit2
! Bit1
! Bit0
|-
|0
|colspan="8"|?
|-
|1
|colspan="8"|GestureID : (Gesture code ,

0x00: no gesture,

0x01: Slide down,

0x02: Slide up,

0x03: Slide left,

0x04: Slide right,

0x05: Single click,

0x0B: Double click,

0x0C: Long press)
|-
|2
|colspan="4"|?
|colspan="4"|Number of touch points
|-
|3
|colspan="2"|Event (0 = Down, 1 = Up, 2 = Contact)
|colspan="2"|?
|colspan="4"|X (MSB) coordinate
|-
|4
|colspan="8"|X (LSB) coordinate
|-
|5
|colspan="2"|?
|colspan="2"|Touch ID
|colspan="4"|Y (MSB) coordinate
|-
|6
|colspan="8"|Y (LSB) coordinate
|-
|7
|colspan="8"|Pressure (?)
|-
|8
|colspan="8"|Miscellaneous (?)
|}

Bytes 3 to 8 are repeated 10 times (10*6 + 3 = 63 bytes).

'''NOTES'''

* The touch controller seems to report only 1 touch point
* Fields X, Y, Number of touch points and touch ID are updated. The others are always 0.

==== Registers ====

The reference driver specifies some registers and value, but there is no information about them:

{| class="wikitable"

!Register
!Address
!Description
|-
|HYN_REG_INT_CNT
|0x8F
|
|-
|HYN_REG_FLOW_WORK_CNT
|0x91
|
|-
|HYN_REG_WORKMODE
|0x00
|0 = WORK, 0x40 = FACTORY
|-
|HYN_REG_CHIP_ID
|0xA3
|
|-
|HYN_REG_CHIP_ID2
|0x9F
|-
|HYN_REG_POWER_MODE
|0xA5
|0x03 = SLEEP (reset the touchpanel using the reset pin before using this register : pin_low, delay 5ms, pin_high, delay 50ms then write 3 to register 0xA5)
|-
|HYN_REG_FW_VER
|0xA6
|
|-
|HYN_REG_VENDOR_ID
|0xA8
|
|-
|HYN_REG_LCD_BUSY_NUM
|0xAB
|
|-
|HYN_REG_FACE_DEC_MODE_EN
|0xB0
|
|-
|HYN_REG_GLOVE_MODE_EN
|0xC0
|
|-
|HYN_REG_COVER_MODE_EN
|0xC1
|
|-
|HYN_REG_CHARGER_MODE_EN
|0x8B
|
|-
|HYN_REG_GESTURE_EN
|0xD0
|
|-
|HYN_REG_GESTURE_OUTPUT_ADDRESS
|0xD3
|
|-
|HYN_REG_ESD_SATURATE 0xED
|0xED
|
|}

'''WARNING : ''' <del>Writing the SLEEP command (write 0x05 in HYN_REG_POWER_MODE) seems to freeze the controller (it returns only static values) until the battery is totally drained and the whole system reset. Analysis and debugging is more than welcome!</del>

===Accelerometer===
The on board accelerometer is Bosch BMA421, connected to the I2C bus.

==== Pins ====

* P0.06 : I²C SDA
* P0.07 : I²C SCL
* P0.08 : Interrupt

I2C Device address : 0x18

== Datasheets and Schematics ==

=== Schematics ===
* [https://files.pine64.org/doc/PineTime/PineTime%20Schematic-V1.0a-20191103.pdf PineTime Schematic ver1.0a]
* [https://files.pine64.org/doc/PineTime/PineTime%20Port%20Assignment%20rev1.0.pdf PineTime GPIO Port Assignment ver1.0]

Note: The part number for the SPI FLASH in the schematic diagram is not correct, the PineTime features a larger external FLASH device, see below.

=== Chip Datasheets ===
* NORDIC nRF52832 information:
** [https://files.pine64.org/doc/datasheet/pinetime/nRF52832%20product%20brief.pdf nRF52832 Product Brief]
** [https://infocenter.nordicsemi.com/pdf/nRF52832_PS_v1.1.pdf nRF52832 Product Specification v1.1]
* ARMv7-M information:
** [https://static.docs.arm.com/ddi0403/eb/DDI0403E_B_armv7m_arm.pdf ARMv7-M Architecture Reference Manual]

=== Component Datasheets ===
* PMU (Power Management Unit) information:
** [https://files.pine64.org/doc/datasheet/pinetime/SGM40561.pdf SGMicro SGM40561 Single Cell Charger Datasheet]
** [https://files.pine64.org/doc/datasheet/pinetime/SGMICRO-SGM2036.pdf SGMicro SGM2036 3.3V Low Power Low Dropout RF Linear Regulator Datasheet]
* SPI Flash information:
** [https://www.elnec.com/en/device/XTX/XT25F32B+%28QuadSPI%29+%5BSOP8-200%5D/ XTX XT25F32B 32Mb(4MB) SPI NOR Flash] (data sheets for this part are hard to find but it acts similar to other QuadSPI SPI NOR Flash such as [https://www.macronix.com/Lists/Datasheet/Attachments/7426/MX25L3233F,%203V,%2032Mb,%20v1.6.pdf Macronix 32Mb(4MB) SPI NOR Flash])
** [https://datasheet.lcsc.com/szlcsc/2005251035_XTX-XT25F32BSOIGU-S_C558851.pdf XTX XT25F32B]
** IDs for XT25F32B are: manufacturer (0x0b), device (0x15), memory type (0x40), density (0x16)
* LCD Panel:
** [https://files.pine64.org/doc/datasheet/pinetime/PineTime%20LCD%20Panel.jpg 1.3" 240x240 IPS LCD Panel Specification for PineTime]
** [https://wiki.pine64.org/images/5/54/ST7789V_v1.6.pdf 11.6" Sitronix LCD Driver/Controller Datasheet]
* Touchpad information:
** [https://files.pine64.org/doc/datasheet/pinetime/PineTime%20Touch%20Panel.jpg Touchpad Specification for PineTimel]
** [https://files.pine64.org/doc/datasheet/pinetime/CST816S数据手册V1.1.pdf 11.6" Hynitron CST816S Capacitive Touch Controller Datasheet in Chinese]
** [https://wiki.pine64.org/images/2/2f/CST816S.zip Touch Controller Datasheet en]
* Sensor:
** [https://files.pine64.org/doc/datasheet/pinetime/BST-BMA421-FL000.pdf BOSCH BMA421 Triaxial VAcceleration Sensor Product Brief]
** [https://wiki.pine64.org/images/c/cc/Bst-bma400-ds000.pdf BOSCH BMA400 3-axes ultra-low power accelerometer datasheet]
** [https://files.pine64.org/doc/datasheet/pinetime/HRS3300%20Heart%20Rate%20Sensor.pdf TianYiHeXin HRS3300 PPG Heart Rate Sensor Data Sheet]

[[Category:PineTime]]

PineTime Custom Watchface Tutorial

2020-09-27T06:51:57Z

Electr0lyte: /* Creating an Object from the Array */

=PineTime Custom Watchface Tutorial=

This is a tutorial to help new users create custom watchfaces based on the InfiniTime Firmware for Pinetime made by user JF002, thanks to him for its development...

We will explain some of the things we went through while creating some custom Watchfaces, so consider this as a log of experiments of sorts..

So stay tuned to it as it will be dynamically updated...

==What you need to start==
The entire building process will be done by GitHub, so all you need is a device which can give you a Github Web Client, a PC or tablet to give you enough screen space to review your code and a steady internet connection.

Since the compiling and file management is done by Github online, you have nothing else to worry about other than working with the files that display the watch face.

So with those things settled, let's start with the basics of a watchface.

Please remember that this is a wiki, so you can make an account and help us improve this page.

Please make sure not to unilaterally remove info though, but offer an alternative. If it is indeed a better way, in time your alternative will grow into the main text, and the latter info will be pruned.

==Overview==
The Firmware (also called InfiniTime) we will be working with is made with a programming language named '''C++''':[https://en.wikipedia.org/wiki/C%2B%2B]

Basic knowledge of C/C++ is required to to understand the advanced watch faces as that requires more complex code, but you can still do a some cool things without much knowledge of C++ programming, just some small edits to existing programs.

InfiniTime uses the '''LVGL''':[https://lvgl.io] graphics library to provide users with a simple and clean UI without overpowering the Nordic '''nRF52832''':[http://files.pine64.org/doc/datasheet/pinetime/nRF52832%20product%20brief.pdf] microcontroller which is the brain of the watch.

To get the watchface to work there are these basic steps. We will go over each step separately, so don't be daunted, all will become clear soon.

For now we will, modify the the existing watchface, change the positioning of the text labels, add an icon to an existing watchface, and later on we will do a full watchface.

The main file we need to focus on is the '''clock.cpp''' file, it is what contains most of the data attributed to what we see on the watchface, including The time/day characters, the battery and bluetooth icons, and also pedometer count...

so everything we will be doing in the basic modifications is purely messing with this single file.

==Labels==
===What are labels?===
Labels are considered as "elemental" parts that make up a screen's Text-based UI by the LVGL library...
Each label is also considered as an "object" or "obj" and can be manipulated, by changing the data attributed with the "obj", for example, position, internal data like the strings/text etc.
when can change what the label shows and where it shows it...

===Modifying label data===
let's observe something small like the word "BPM" near the bottom of the watch face...
[[file:PineTimeCustom-1.png|right|200px]]

If we take a look at the source file of the watchface, (a.k.a the clock.cpp file)
we can observe that these particular lines are what attributes to the word "BPM being displayed...
heartbeatBpm = lv_label_create(lv_scr_act(), NULL);
lv_label_set_text(heartbeatBpm, "BPM");

we can modify the text inside the quotes and replace the word 'BPM' between those quotes to something like 'LOVE'
and the result after compiling the firmware again with the changes and flashing it to the watch would be that the text changes on the watch face and displays 'LOVE' inplace of 'BPM'...

If this happened correctly, then you have successfully made a custom new watchface! Now we can do something a bit more complex...

Now take for in instance the days of the week that we have on the bottom line with the date...

they are stored a "C array" which is basically multiple words separated by commas..
the date is in a format of '''<day of the week> <day> <Month> <year>'''

which in the source file is expressed as,
sprintf(dateStr, "%s %d %s %d", DayOfWeekToString(dayOfWeek), day, MonthToString(month), year);
lv_label_set_text(label_date, dateStr);

here,
%s %d %s %d
stores the print format of the variables, and

DayOfWeekToString(dayOfWeek), day, MonthToString(month), year
are the variables themselves...

Now,
if the date was a saturday 11/7/2020, you can observe that the date looks like
SATURDAY 11 JUL 2020
as seen in the above image (the one where we changed BPM to LOVE)

by modifying the format of the variables, we can change how those words are arranged, and add some extra characters if we like...
(there is a catch to the list of characters you can use however, but it will be discussed later...)

For example,

We modifying the format by adding a comma... "," in between the second "%s" and "%d" like this,
"%s %d %s, %d"
and changing that in the line...
sprintf(dateStr, "%s %d %s, %d", DayOfWeekToString(dayOfWeek), day, MonthToString(month), year);

we can make the date become...
SATURDAY 11 JUL, 2020

which means we now were able to modify how the text got display to make it a bit more nice...

but if you haven't noticed, the line containing the date is already full, meaning we will get some problems while displaying the date and causing it to wrap around,
making a single character go to the next line and look more like,

SATURDAY 11 JUL, 202
0

so why don't we shorten the characters present in the date from being "SATURDAY" to simply just "sat." (It will have the small period at the end, and is only 3 characters long)
I will also convert the months of the year from Capital to small letters...

for that look into the part where the days of the week of are stored as text,
and also while looking at it, we can solve another question, why was their two variables in the date format that looked like, DayOfWeekToString(dayOfWeek), and MonthToString(month) ?

It is because the system gives the date/ time as numbers (Monday-1, Tuesday-2 Wednesday-3 for the days, and 1-January, 2-February, 3-March ),
and so a function along with a C array is used to assign these numbers to Days/Months in text form as it is easier to read...

this is the Array containing the day of the week, (as text)
char const *Clock::DaysString[] = {
"",
"MONDAY",
"TUESDAY",
"WEDNESDAY",
"THURSDAY",
"FRIDAY",
"SATURDAY",
"SUNDAY"
};

and this Array stores the months of the year, (as text)
char const *Clock::MonthsString[] = {
"",
"JAN",
"FEB",
"MAR",
"APR",
"MAY",
"JUN",
"JUL",
"AUG",
"SEP",
"OCT",
"NOV",
"DEC"
};

here we can see that the days are stored in a full format as "SUNDAY", "MONDAY", "TUESDAY" etc.
we can change all of them to a shorter format like "sun.", "mon.", "tue.", to make it short and nice...
while doing so, we can even make the months use small letters as said before..

so the source file (clock.cpp) becomes,

(for the days of the week)
char const *Clock::DaysString[] = {
"",
"mon.",
"tue.",
"wed.",
"thu.",
"fri.",
"sat.",
"sun."
};

and

(for the months of the year)
char const *Clock::MonthsString[] = {
"",
"jan",
"feb",
"mar",
"apr",
"may",
"jun",
"jul",
"aug",
"sep",
"oct",
"nov",
"dec"
};

which means now our original date, saturday 11/7/2020 will become...
sat. 11 jul, 2020

you now know how to change the data present in a label object, and the format of it..,

Here is a fun idea you can try: you can even replace the days with whatever thing that tells you (or) reminds you the day of the week
(like the food served in the cafe, Monday/taco, Tuesday/burger, Wednesday/pasta etc.)

NOTE: when making the custom array, don't forget to leave a empty "" as the first element of the array,
This is because the date is given by the system in a natural numbers format (1,2,3...) rather than a zero-starting format (0,1,2,3...), which the C array uses to index...
so the C array indexes the days as ""-0, "Monday"-1, "Tuesday"-2 etc. and the months as ""-0, "January"-1, "February"-2 etc.)

===Label positioning===

The locational placement in LVGL is done on a cartesian plane,
where each object can have dynamic origin placement, and the Y-axis is inverted...
So going down is done with a positive Y-axis value and not negative as the it is by de-facto...

[[File:LVGL coord system.png|200px|thumb|right|LVGL coord system]]

The position of the various objects in clock.cpp are set by the line,
lv_obj_set_pos(<obj>, <new_x>, <new_y>)

and the top left corner is the Cartesian origin, aka coordinates (0,0)

this image can show you how to decide label placement for lv_obj_set_pos(...)

we use another function, that is more advanced that gives the positional alignment based on preset locations...
lv_obj_align(<text/obj>, <image/obj>, <location_parameter>, <new_x>, <new_y>);

the "<image/obj>" data is used for putting text beside other picture icons , and so if using only text based labels, we can substitute it with,
lv_scr_act() (or) NULL

'''<new_x>, <new_y>''' are the cartesian coordinates, '''<location parameter>''' is replaced by '''LV_ALIGN_<preset>''',
there will be a picture showing the presets below, and '''<text/obj>''' is your text label...

here, LV_ALIGN_<preset> sets the cartesian origin...

Label positioning based on alignment is both a simple and complicated thing to understand, so here I have given something you can refer to while modifying the position of the various labels and objects...

you can also refer here for LVGL's documentation of coordinate system https://docs.lvgl.io/v6/en/html/object-types/obj.html#coordinates

It is however recommended that you use the first method to set the location
lv_obj_set_pos(<obj>, <new_x>, <new_y>)
as it is simple and easier for beginners

Here is a small example.

Take the Label that tells the date,
In the source file (clock.cpp) it is this line,
lv_obj_align(label_date, lv_scr_act(), LV_ALIGN_IN_LEFT_MID, 0, 60);
by increasing the Value of the Y coordinate (60) to a higher value, we can bring the position of the Date downwards a bit away from the Time, and toward the Heartbeat count in the bottom row
here I will increase it to 80, so it becomes..
lv_obj_align(label_date, lv_scr_act(), LV_ALIGN_IN_LEFT_MID, 0, 80);

and now we have made some space up top..

now let's try something a bit complex,

Take the position argument for the label that tells you time...
here, in the source file (clock.cpp),
lv_obj_align(label_time, lv_scr_act(), LV_ALIGN_IN_LEFT_MID, 0, 0);

this line determines the position of the Label telling time, as seen in the image...

we modifying this, by changing the origin <preset> parameter (here it is LV_ALIGN_IN_LEFT_MID) to LV_ALIGN_IN_TOP_LEFT

you can alternatively swap the whole line to,
lv_obj_set_pos(label_time, 0, 0);

this makes the Time label/obj. to go to the top left corner...

but I will do something a little extra,
I will modify the label that store the data and Time format,
i.e this line,
sprintf(timeStr, "%c%c:%c%c", hoursChar[0],hoursChar[1],minutesChar[0], minutesChar[1]);

by removing the ":" colon in between the numbers, and replacing it with a Newline symbol "\n"
I change it to become,
sprintf(timeStr, "%c%c\n%c%c", hoursChar[0],hoursChar[1],minutesChar[0], minutesChar[1]);

this gives it a nice wrapped text format in the top corner, and gives us some space to play with in the side, for things like Pictures and icons, which we will do next..

If you have been able to do these things, you now have completed the 2nd part of the tutorial, and now know how to change and modify the position of labels..

==Using icons==
The LVGL library allows for the use of widgets known as "Images", In short it allows you to use small Icons like pictures with a small dedicated function,
However when this was attempted the first time we stumbled on some problems as LVGL v6 (used on the pinetime) is not much documented as the latest release (v7 as of August 2020)
but also the existing code was only documented for C not C++, after some painful attempts we were able to translate it into C++,

To bring images into Clock.cpp
you will need to do the following,

1. Have a small image that cannot exceed a maximum size of 240px x 240px (pinetime max resolution)

2. Use this Image converter (Thanks to LVGL) https://lvgl.io/tools/imageconverter
to convert your image to a C array and having the Color format as "True color" and the output format as "C array"
make sure to use something simple as the name we will be using "bitmap" as the name, but will also be referred as <name> for simplicity

Note: for example we shall use <name> = bitmap, but any simple word can be used, as long as it does not cause problems with system variables

===Image size considerations===
since the image will be using the flash directly, we need to be considerate about flash memory usage.

<picture_X> x <picture_Y> x 2
gives you the number of KB the image used in storage...

where, <picture_X> <picture_Y> are the dimensions of the image horizontally and vertically

for example,
if <picture_X>=80px <picture_Y>=64px
then,
total storage used = 80 x 60 x 2 = 10.24KB

please use the flash storage with consideration, when using other apps as well, excess usage of storage
might mean the Firmware will not compile... the limit to storage to about 400Kb for the user, the
firmware size must not exceed that...

==Preparing the image for inclusion as an icon==

Once you have your obtained your C array from the LVGL converter, you can take a look inside it to see all the different formats of your image,
try using something like Notepad++ or any of your favorite text editors to peek inside of it,

there will be 4 sets of Arrays inside it that look like,

#if LV_COLOR_DEPTH == 1 || LV_COLOR_DEPTH == 8
/*Pixel format: Red: 3 bit, Green: 3 bit, Blue: 2 bit*/
0x00, 0x00, 0x00,...
...0x00, 0x00, 0x00,
#endif

#if LV_COLOR_DEPTH == 16 && LV_COLOR_16_SWAP == 0
/*Pixel format: Red: 5 bit, Green: 6 bit, Blue: 5 bit*/
0x00, 0x00, 0x00,...
...0x00, 0x00, 0x00,
#endif

#if LV_COLOR_DEPTH == 16 && LV_COLOR_16_SWAP != 0
/*Pixel format: Red: 5 bit, Green: 6 bit, Blue: 5 bit BUT the 2 bytes are swapped*/
0x00, 0x00, 0x00,...
...0x00, 0x00, 0x00,
#endif

#if LV_COLOR_DEPTH == 32
/*Pixel format: Fix 0xFF: 8 bit, Red: 8 bit, Green: 8 bit, Blue: 8 bit*/
0x00, 0x00, 0x00,...
...0x00, 0x00, 0xff,
#endif
};

And another small bit of info we will need for later that looks like,

const lv_img_dsc_t bitmap = {
.header.always_zero = 0,
.header.w = 40,
.header.h = 40,
.data_size = 1600 * LV_COLOR_SIZE / 8,
.header.cf = LV_IMG_CF_TRUE_COLOR,
.data = bitmap_map,
};

NOTE: There are some header files at the top, which we can ignore...
===RGB565 image format===

The Pinetime uses a display that uses a 16 bit color space, also known as RGB565.

These 16 bit are assigned to RGB as 5 bits each for Red and Blue and 6 bits for Green, so 5+6+5=16 bits are required, so each pixel's color occupies 2 bytes of data,
and since 216 is equal to 65,536 it allows us to view 65,536 or 65k colors

The way it packs these bits is by converting the bits into 2x 4+4 bit hex-code, so for example,

if the color of a pixel in Binary is '''10110100 01011111''' (this color is approximately Lavender purple)

It is split as '''1011''' & '''0100''' for the first byte and '''0101''' & '''1111''' for the second byte
and so, converting the binary into Hex-code,

the two parts are '''0xB4''' and '''0xF5'''

These two parts in conjunction are used for determining the color of one pixel...

also from the binary, it is observed that,

The bits '''10110''' is used for Red, '''100010''' is used for green, and '''11111''' is used for blue.

===Flipping the bytes===
The LVGL library has a feature that allows you to flip the two bytes of the pixel, so if the two parts were, ...0xB4,0xF5,... ,it will change it to become, ...0xF5,0xB4,...

The reason for this is to allow the use of 8-bit SPI interfaces, but we do not require it, and if set with wrong parameter we could get problems with the color...

To make sure you are ready for the next step, make sure that inside your lvgl configuration file (located at '''src/libs/lv_conf.h''')

this parameter,
'''#define LV_COLOR_16_SWAP 1'''
is set to "1" as seen...

NOTE: if you haven't modified it or tampered with it with your Github fork, you shouldn't have a problem
as it is correct by default, and you can skip these steps

===Creating an Object from the Array===
To include the Icon, first Identify the Array you need to copy to the source (clock.cpp)

The one we require from it is the data below the tag that looks like,
#if LV_COLOR_DEPTH == 16 && LV_COLOR_16_SWAP != 0
/*Pixel format: Red: 5 bit, Green: 6 bit, Blue: 5 bit BUT the 2 bytes are swapped*/
0x00, 0x00, 0x00,...
...0x00, 0x00, 0x00,
#endif

from this copy the Data from the array alone...
I.e this part,
0x00, 0x00, 0x00,...
...0x00, 0x00, 0x00

(Make sure to not include the comma at the end or the #endif as the entire part is going to substitute a new array)

In clock.cpp, just below the header files and the Task creation part (I.e event_handler...),

static void event_handler(lv_obj_t * obj, lv_event_t event) {
Clock* screen = static_cast<Clock *>(obj->user_data);
screen->OnObjectEvent(obj, event);
}

create a name for the label with,
static lv_img_dsc_t <name>; // remember to replace <name> with the actual name you gave to your image while converting !

then below it create a array to hold the data with,
const uint8_t <name>_map[] = {}; // paste the array you copied from the conversion file we specified above...

so your array is something like,

const uint8_t <name>_map[] = {0x00,0x00,0x00...
...0x00,0x00,0x00};

so your Entire top region of declaration looks like,

#include <cstdio>
#include <libs/date/includes/date/date.h>
...
using namespace Pinetime::Applications::Screens;
extern lv_font_t jetbrains_mono_extrabold_compressed;
extern lv_font_t jetbrains_mono_bold_20;
extern lv_style_t* LabelBigStyle;
''' '''
static void event_handler(lv_obj_t * obj, lv_event_t event) {
Clock* screen = static_cast<Clock *>(obj->user_data);
screen->OnObjectEvent(obj, event);
}
''' '''
'''//Declare the descriptor here'''
static lv_img_dsc_t <name>;
'''//place the Image data here
const uint8_t <name>_map[] = {0x00,0x00,0x00...
...0x00,0x00,0x00
};

'''note: Declaring variables outside a function like we did above is known as global scope declaration, this means the variable can be used by not just one function but the Entire code...'''

Then inside the
Clock::Clock(DisplayApp* app,...){...
region, (the watchface function)
You need to place a particular set of lines which LVGL uses to define the object declare the array as an Icon/Image, You can place this set of lines above label_time...

<name>.header.always_zero = 0; //Initialization
<name>.header.w = <picture_X>; // Setting the Width (or) Horizontal length of the image (number of px)
<name>.header.h = <picture_Y>; // Setting the Height (or) vertical length of the image (number of px)
<name>.data_size = <Hr_length> * <Vr_length> * LV_COLOR_SIZE / 8; //Allocation of memory for the image
<name>.header.cf = LV_IMG_CF_TRUE_COLOR; // Sets the color scheme for the image
<name>.data = <name>_map; // Maps the Image data to the Array
lv_obj_t *img_src = lv_img_create(lv_scr_act(), NULL); // Create an image object
lv_img_set_src(img_src, &<name>); // Set the created file as image (<name>)

again, make sure to replace <name> with the name you gave it during conversion!

Now that we have bought in the image data, we need to set the position, you can place this just below the lines we wrote for bringing in the image, It can be done with either,
lv_obj_set_pos(img_src, <x_pos, <y_pos>); // <x_pos>, <y_pos> are the coordinates of the cartesian plane
or,
lv_obj_align(img_src, lv_scr_act(), LV_ALIGN_<parameter>, <x_pos, <y_pos>);

If done correctly, you will now have a beautiful little Icon/Image in your Watch face,
Make sure that your Watch face can accommodate the Image by pushing the other labels farther away creating space for it...

We have provided a small template you can use for adding even a large image comfortably

If you have succeeded with this, you have completed part 3 of the tutorial.

=Using git to work on the firmware=
===Cloning the repository===
===Changing the code to add the image===
===Compiling the firmware===
==Testing the firmware==
===Installing the new firmware===

A holistic guide on how to install different firmware using various hardware programmers is available here: [[Reprogramming the PineTime]]. There's also the possibility of using OTA updating. ''//TODO: add that to the article!''

===Activating the firmware===
===How to troubleshoot===
==Conclusions==
==Next steps==
==More in-depth documentation==
==Thanks for the help==

PineTime Custom Watchface Tutorial

2020-09-27T06:50:49Z

Electr0lyte: /* Creating an Object from the Array */

=PineTime Custom Watchface Tutorial=

This is a tutorial to help new users create custom watchfaces based on the InfiniTime Firmware for Pinetime made by user JF002, thanks to him for its development...

We will explain some of the things we went through while creating some custom Watchfaces, so consider this as a log of experiments of sorts..

So stay tuned to it as it will be dynamically updated...

==What you need to start==
The entire building process will be done by GitHub, so all you need is a device which can give you a Github Web Client, a PC or tablet to give you enough screen space to review your code and a steady internet connection.

Since the compiling and file management is done by Github online, you have nothing else to worry about other than working with the files that display the watch face.

So with those things settled, let's start with the basics of a watchface.

Please remember that this is a wiki, so you can make an account and help us improve this page.

Please make sure not to unilaterally remove info though, but offer an alternative. If it is indeed a better way, in time your alternative will grow into the main text, and the latter info will be pruned.

==Overview==
The Firmware (also called InfiniTime) we will be working with is made with a programming language named '''C++''':[https://en.wikipedia.org/wiki/C%2B%2B]

Basic knowledge of C/C++ is required to to understand the advanced watch faces as that requires more complex code, but you can still do a some cool things without much knowledge of C++ programming, just some small edits to existing programs.

InfiniTime uses the '''LVGL''':[https://lvgl.io] graphics library to provide users with a simple and clean UI without overpowering the Nordic '''nRF52832''':[http://files.pine64.org/doc/datasheet/pinetime/nRF52832%20product%20brief.pdf] microcontroller which is the brain of the watch.

To get the watchface to work there are these basic steps. We will go over each step separately, so don't be daunted, all will become clear soon.

For now we will, modify the the existing watchface, change the positioning of the text labels, add an icon to an existing watchface, and later on we will do a full watchface.

The main file we need to focus on is the '''clock.cpp''' file, it is what contains most of the data attributed to what we see on the watchface, including The time/day characters, the battery and bluetooth icons, and also pedometer count...

so everything we will be doing in the basic modifications is purely messing with this single file.

==Labels==
===What are labels?===
Labels are considered as "elemental" parts that make up a screen's Text-based UI by the LVGL library...
Each label is also considered as an "object" or "obj" and can be manipulated, by changing the data attributed with the "obj", for example, position, internal data like the strings/text etc.
when can change what the label shows and where it shows it...

===Modifying label data===
let's observe something small like the word "BPM" near the bottom of the watch face...
[[file:PineTimeCustom-1.png|right|200px]]

If we take a look at the source file of the watchface, (a.k.a the clock.cpp file)
we can observe that these particular lines are what attributes to the word "BPM being displayed...
heartbeatBpm = lv_label_create(lv_scr_act(), NULL);
lv_label_set_text(heartbeatBpm, "BPM");

we can modify the text inside the quotes and replace the word 'BPM' between those quotes to something like 'LOVE'
and the result after compiling the firmware again with the changes and flashing it to the watch would be that the text changes on the watch face and displays 'LOVE' inplace of 'BPM'...

If this happened correctly, then you have successfully made a custom new watchface! Now we can do something a bit more complex...

Now take for in instance the days of the week that we have on the bottom line with the date...

they are stored a "C array" which is basically multiple words separated by commas..
the date is in a format of '''<day of the week> <day> <Month> <year>'''

which in the source file is expressed as,
sprintf(dateStr, "%s %d %s %d", DayOfWeekToString(dayOfWeek), day, MonthToString(month), year);
lv_label_set_text(label_date, dateStr);

here,
%s %d %s %d
stores the print format of the variables, and

DayOfWeekToString(dayOfWeek), day, MonthToString(month), year
are the variables themselves...

Now,
if the date was a saturday 11/7/2020, you can observe that the date looks like
SATURDAY 11 JUL 2020
as seen in the above image (the one where we changed BPM to LOVE)

by modifying the format of the variables, we can change how those words are arranged, and add some extra characters if we like...
(there is a catch to the list of characters you can use however, but it will be discussed later...)

For example,

We modifying the format by adding a comma... "," in between the second "%s" and "%d" like this,
"%s %d %s, %d"
and changing that in the line...
sprintf(dateStr, "%s %d %s, %d", DayOfWeekToString(dayOfWeek), day, MonthToString(month), year);

we can make the date become...
SATURDAY 11 JUL, 2020

which means we now were able to modify how the text got display to make it a bit more nice...

but if you haven't noticed, the line containing the date is already full, meaning we will get some problems while displaying the date and causing it to wrap around,
making a single character go to the next line and look more like,

SATURDAY 11 JUL, 202
0

so why don't we shorten the characters present in the date from being "SATURDAY" to simply just "sat." (It will have the small period at the end, and is only 3 characters long)
I will also convert the months of the year from Capital to small letters...

for that look into the part where the days of the week of are stored as text,
and also while looking at it, we can solve another question, why was their two variables in the date format that looked like, DayOfWeekToString(dayOfWeek), and MonthToString(month) ?

It is because the system gives the date/ time as numbers (Monday-1, Tuesday-2 Wednesday-3 for the days, and 1-January, 2-February, 3-March ),
and so a function along with a C array is used to assign these numbers to Days/Months in text form as it is easier to read...

this is the Array containing the day of the week, (as text)
char const *Clock::DaysString[] = {
"",
"MONDAY",
"TUESDAY",
"WEDNESDAY",
"THURSDAY",
"FRIDAY",
"SATURDAY",
"SUNDAY"
};

and this Array stores the months of the year, (as text)
char const *Clock::MonthsString[] = {
"",
"JAN",
"FEB",
"MAR",
"APR",
"MAY",
"JUN",
"JUL",
"AUG",
"SEP",
"OCT",
"NOV",
"DEC"
};

here we can see that the days are stored in a full format as "SUNDAY", "MONDAY", "TUESDAY" etc.
we can change all of them to a shorter format like "sun.", "mon.", "tue.", to make it short and nice...
while doing so, we can even make the months use small letters as said before..

so the source file (clock.cpp) becomes,

(for the days of the week)
char const *Clock::DaysString[] = {
"",
"mon.",
"tue.",
"wed.",
"thu.",
"fri.",
"sat.",
"sun."
};

and

(for the months of the year)
char const *Clock::MonthsString[] = {
"",
"jan",
"feb",
"mar",
"apr",
"may",
"jun",
"jul",
"aug",
"sep",
"oct",
"nov",
"dec"
};

which means now our original date, saturday 11/7/2020 will become...
sat. 11 jul, 2020

you now know how to change the data present in a label object, and the format of it..,

Here is a fun idea you can try: you can even replace the days with whatever thing that tells you (or) reminds you the day of the week
(like the food served in the cafe, Monday/taco, Tuesday/burger, Wednesday/pasta etc.)

NOTE: when making the custom array, don't forget to leave a empty "" as the first element of the array,
This is because the date is given by the system in a natural numbers format (1,2,3...) rather than a zero-starting format (0,1,2,3...), which the C array uses to index...
so the C array indexes the days as ""-0, "Monday"-1, "Tuesday"-2 etc. and the months as ""-0, "January"-1, "February"-2 etc.)

===Label positioning===

The locational placement in LVGL is done on a cartesian plane,
where each object can have dynamic origin placement, and the Y-axis is inverted...
So going down is done with a positive Y-axis value and not negative as the it is by de-facto...

[[File:LVGL coord system.png|200px|thumb|right|LVGL coord system]]

The position of the various objects in clock.cpp are set by the line,
lv_obj_set_pos(<obj>, <new_x>, <new_y>)

and the top left corner is the Cartesian origin, aka coordinates (0,0)

this image can show you how to decide label placement for lv_obj_set_pos(...)

we use another function, that is more advanced that gives the positional alignment based on preset locations...
lv_obj_align(<text/obj>, <image/obj>, <location_parameter>, <new_x>, <new_y>);

the "<image/obj>" data is used for putting text beside other picture icons , and so if using only text based labels, we can substitute it with,
lv_scr_act() (or) NULL

'''<new_x>, <new_y>''' are the cartesian coordinates, '''<location parameter>''' is replaced by '''LV_ALIGN_<preset>''',
there will be a picture showing the presets below, and '''<text/obj>''' is your text label...

here, LV_ALIGN_<preset> sets the cartesian origin...

Label positioning based on alignment is both a simple and complicated thing to understand, so here I have given something you can refer to while modifying the position of the various labels and objects...

you can also refer here for LVGL's documentation of coordinate system https://docs.lvgl.io/v6/en/html/object-types/obj.html#coordinates

It is however recommended that you use the first method to set the location
lv_obj_set_pos(<obj>, <new_x>, <new_y>)
as it is simple and easier for beginners

Here is a small example.

Take the Label that tells the date,
In the source file (clock.cpp) it is this line,
lv_obj_align(label_date, lv_scr_act(), LV_ALIGN_IN_LEFT_MID, 0, 60);
by increasing the Value of the Y coordinate (60) to a higher value, we can bring the position of the Date downwards a bit away from the Time, and toward the Heartbeat count in the bottom row
here I will increase it to 80, so it becomes..
lv_obj_align(label_date, lv_scr_act(), LV_ALIGN_IN_LEFT_MID, 0, 80);

and now we have made some space up top..

now let's try something a bit complex,

Take the position argument for the label that tells you time...
here, in the source file (clock.cpp),
lv_obj_align(label_time, lv_scr_act(), LV_ALIGN_IN_LEFT_MID, 0, 0);

this line determines the position of the Label telling time, as seen in the image...

we modifying this, by changing the origin <preset> parameter (here it is LV_ALIGN_IN_LEFT_MID) to LV_ALIGN_IN_TOP_LEFT

you can alternatively swap the whole line to,
lv_obj_set_pos(label_time, 0, 0);

this makes the Time label/obj. to go to the top left corner...

but I will do something a little extra,
I will modify the label that store the data and Time format,
i.e this line,
sprintf(timeStr, "%c%c:%c%c", hoursChar[0],hoursChar[1],minutesChar[0], minutesChar[1]);

by removing the ":" colon in between the numbers, and replacing it with a Newline symbol "\n"
I change it to become,
sprintf(timeStr, "%c%c\n%c%c", hoursChar[0],hoursChar[1],minutesChar[0], minutesChar[1]);

this gives it a nice wrapped text format in the top corner, and gives us some space to play with in the side, for things like Pictures and icons, which we will do next..

If you have been able to do these things, you now have completed the 2nd part of the tutorial, and now know how to change and modify the position of labels..

==Using icons==
The LVGL library allows for the use of widgets known as "Images", In short it allows you to use small Icons like pictures with a small dedicated function,
However when this was attempted the first time we stumbled on some problems as LVGL v6 (used on the pinetime) is not much documented as the latest release (v7 as of August 2020)
but also the existing code was only documented for C not C++, after some painful attempts we were able to translate it into C++,

To bring images into Clock.cpp
you will need to do the following,

1. Have a small image that cannot exceed a maximum size of 240px x 240px (pinetime max resolution)

2. Use this Image converter (Thanks to LVGL) https://lvgl.io/tools/imageconverter
to convert your image to a C array and having the Color format as "True color" and the output format as "C array"
make sure to use something simple as the name we will be using "bitmap" as the name, but will also be referred as <name> for simplicity

Note: for example we shall use <name> = bitmap, but any simple word can be used, as long as it does not cause problems with system variables

===Image size considerations===
since the image will be using the flash directly, we need to be considerate about flash memory usage.

<picture_X> x <picture_Y> x 2
gives you the number of KB the image used in storage...

where, <picture_X> <picture_Y> are the dimensions of the image horizontally and vertically

for example,
if <picture_X>=80px <picture_Y>=64px
then,
total storage used = 80 x 60 x 2 = 10.24KB

please use the flash storage with consideration, when using other apps as well, excess usage of storage
might mean the Firmware will not compile... the limit to storage to about 400Kb for the user, the
firmware size must not exceed that...

==Preparing the image for inclusion as an icon==

Once you have your obtained your C array from the LVGL converter, you can take a look inside it to see all the different formats of your image,
try using something like Notepad++ or any of your favorite text editors to peek inside of it,

there will be 4 sets of Arrays inside it that look like,

#if LV_COLOR_DEPTH == 1 || LV_COLOR_DEPTH == 8
/*Pixel format: Red: 3 bit, Green: 3 bit, Blue: 2 bit*/
0x00, 0x00, 0x00,...
...0x00, 0x00, 0x00,
#endif

#if LV_COLOR_DEPTH == 16 && LV_COLOR_16_SWAP == 0
/*Pixel format: Red: 5 bit, Green: 6 bit, Blue: 5 bit*/
0x00, 0x00, 0x00,...
...0x00, 0x00, 0x00,
#endif

#if LV_COLOR_DEPTH == 16 && LV_COLOR_16_SWAP != 0
/*Pixel format: Red: 5 bit, Green: 6 bit, Blue: 5 bit BUT the 2 bytes are swapped*/
0x00, 0x00, 0x00,...
...0x00, 0x00, 0x00,
#endif

#if LV_COLOR_DEPTH == 32
/*Pixel format: Fix 0xFF: 8 bit, Red: 8 bit, Green: 8 bit, Blue: 8 bit*/
0x00, 0x00, 0x00,...
...0x00, 0x00, 0xff,
#endif
};

And another small bit of info we will need for later that looks like,

const lv_img_dsc_t bitmap = {
.header.always_zero = 0,
.header.w = 40,
.header.h = 40,
.data_size = 1600 * LV_COLOR_SIZE / 8,
.header.cf = LV_IMG_CF_TRUE_COLOR,
.data = bitmap_map,
};

NOTE: There are some header files at the top, which we can ignore...
===RGB565 image format===

The Pinetime uses a display that uses a 16 bit color space, also known as RGB565.

These 16 bit are assigned to RGB as 5 bits each for Red and Blue and 6 bits for Green, so 5+6+5=16 bits are required, so each pixel's color occupies 2 bytes of data,
and since 216 is equal to 65,536 it allows us to view 65,536 or 65k colors

The way it packs these bits is by converting the bits into 2x 4+4 bit hex-code, so for example,

if the color of a pixel in Binary is '''10110100 01011111''' (this color is approximately Lavender purple)

It is split as '''1011''' & '''0100''' for the first byte and '''0101''' & '''1111''' for the second byte
and so, converting the binary into Hex-code,

the two parts are '''0xB4''' and '''0xF5'''

These two parts in conjunction are used for determining the color of one pixel...

also from the binary, it is observed that,

The bits '''10110''' is used for Red, '''100010''' is used for green, and '''11111''' is used for blue.

===Flipping the bytes===
The LVGL library has a feature that allows you to flip the two bytes of the pixel, so if the two parts were, ...0xB4,0xF5,... ,it will change it to become, ...0xF5,0xB4,...

The reason for this is to allow the use of 8-bit SPI interfaces, but we do not require it, and if set with wrong parameter we could get problems with the color...

To make sure you are ready for the next step, make sure that inside your lvgl configuration file (located at '''src/libs/lv_conf.h''')

this parameter,
'''#define LV_COLOR_16_SWAP 1'''
is set to "1" as seen...

NOTE: if you haven't modified it or tampered with it with your Github fork, you shouldn't have a problem
as it is correct by default, and you can skip these steps

===Creating an Object from the Array===
To include the Icon, first Identify the Array you need to copy to the source (clock.cpp)

The one we require from it is the data below the tag that looks like,
#if LV_COLOR_DEPTH == 16 && LV_COLOR_16_SWAP != 0
/*Pixel format: Red: 5 bit, Green: 6 bit, Blue: 5 bit BUT the 2 bytes are swapped*/
0x00, 0x00, 0x00,...
...0x00, 0x00, 0x00,
#endif

from this copy the Data from the array alone...
I.e this part,
0x00, 0x00, 0x00,...
...0x00, 0x00, 0x00

(Make sure to not include the comma at the end or the #endif as the entire part is going to substitute a new array)

In clock.cpp, just below the header files and the Task creation part (I.e event_handler...),

static void event_handler(lv_obj_t * obj, lv_event_t event) {
Clock* screen = static_cast<Clock *>(obj->user_data);
screen->OnObjectEvent(obj, event);
}

create a name for the label with,
static lv_img_dsc_t <name>; // remember to replace <name> with the actual name you gave to your image while converting !

then below it create a array to hold the data with,
const uint8_t <name>_map[] = {}; // paste the array you copied from the conversion file we specified above...

so your array is something like,

const uint8_t <name>_map[] = {0x00,0x00,0x00...
...0x00,0x00,0x00};

so your Entire top region of declaration looks like,

#include <cstdio>
#include <libs/date/includes/date/date.h>
...
using namespace Pinetime::Applications::Screens;
extern lv_font_t jetbrains_mono_extrabold_compressed;
extern lv_font_t jetbrains_mono_bold_20;
extern lv_style_t* LabelBigStyle;
''' '''
static void event_handler(lv_obj_t * obj, lv_event_t event) {
Clock* screen = static_cast<Clock *>(obj->user_data);
screen->OnObjectEvent(obj, event);
}
''' '''
'''//Declare the descriptor here'''
static lv_img_dsc_t <name>;
'''//place the Image data here
const uint8_t bitmap_map[] = {0x00,0x00,0x00...
...0x00,0x00,0x00
};

'''note: Declaring variables outside a function like we did above is known as global scope declaration, this means the variable can be used by not just one function but the Entire code...'''

Then inside the
Clock::Clock(DisplayApp* app,...){...
region, (the watchface function)
You need to place a particular set of lines which LVGL uses to define the object declare the array as an Icon/Image, You can place this set of lines above label_time...

<name>.header.always_zero = 0; //Initialization
<name>.header.w = <picture_X>; // Setting the Width (or) Horizontal length of the image (number of px)
<name>.header.h = <picture_Y>; // Setting the Height (or) vertical length of the image (number of px)
<name>.data_size = <Hr_length> * <Vr_length> * LV_COLOR_SIZE / 8; //Allocation of memory for the image
<name>.header.cf = LV_IMG_CF_TRUE_COLOR; // Sets the color scheme for the image
<name>.data = <name>_map; // Maps the Image data to the Array
lv_obj_t *img_src = lv_img_create(lv_scr_act(), NULL); // Create an image object
lv_img_set_src(img_src, &<name>); // Set the created file as image (<name>)

again, make sure to replace <name> with the name you gave it during conversion!

Now that we have bought in the image data, we need to set the position, you can place this just below the lines we wrote for bringing in the image, It can be done with either,
lv_obj_set_pos(img_src, <x_pos, <y_pos>); // <x_pos>, <y_pos> are the coordinates of the cartesian plane
or,
lv_obj_align(img_src, lv_scr_act(), LV_ALIGN_<parameter>, <x_pos, <y_pos>);

If done correctly, you will now have a beautiful little Icon/Image in your Watch face,
Make sure that your Watch face can accommodate the Image by pushing the other labels farther away creating space for it...

We have provided a small template you can use for adding even a large image comfortably

If you have succeeded with this, you have completed part 3 of the tutorial.

=Using git to work on the firmware=
===Cloning the repository===
===Changing the code to add the image===
===Compiling the firmware===
==Testing the firmware==
===Installing the new firmware===

A holistic guide on how to install different firmware using various hardware programmers is available here: [[Reprogramming the PineTime]]. There's also the possibility of using OTA updating. ''//TODO: add that to the article!''

===Activating the firmware===
===How to troubleshoot===
==Conclusions==
==Next steps==
==More in-depth documentation==
==Thanks for the help==

PineTime Custom Watchface Tutorial

2020-09-27T06:48:51Z

Electr0lyte: /* Creating an Object from the Array */

=PineTime Custom Watchface Tutorial=

This is a tutorial to help new users create custom watchfaces based on the InfiniTime Firmware for Pinetime made by user JF002, thanks to him for its development...

We will explain some of the things we went through while creating some custom Watchfaces, so consider this as a log of experiments of sorts..

So stay tuned to it as it will be dynamically updated...

==What you need to start==
The entire building process will be done by GitHub, so all you need is a device which can give you a Github Web Client, a PC or tablet to give you enough screen space to review your code and a steady internet connection.

Since the compiling and file management is done by Github online, you have nothing else to worry about other than working with the files that display the watch face.

So with those things settled, let's start with the basics of a watchface.

Please remember that this is a wiki, so you can make an account and help us improve this page.

Please make sure not to unilaterally remove info though, but offer an alternative. If it is indeed a better way, in time your alternative will grow into the main text, and the latter info will be pruned.

==Overview==
The Firmware (also called InfiniTime) we will be working with is made with a programming language named '''C++''':[https://en.wikipedia.org/wiki/C%2B%2B]

Basic knowledge of C/C++ is required to to understand the advanced watch faces as that requires more complex code, but you can still do a some cool things without much knowledge of C++ programming, just some small edits to existing programs.

InfiniTime uses the '''LVGL''':[https://lvgl.io] graphics library to provide users with a simple and clean UI without overpowering the Nordic '''nRF52832''':[http://files.pine64.org/doc/datasheet/pinetime/nRF52832%20product%20brief.pdf] microcontroller which is the brain of the watch.

To get the watchface to work there are these basic steps. We will go over each step separately, so don't be daunted, all will become clear soon.

For now we will, modify the the existing watchface, change the positioning of the text labels, add an icon to an existing watchface, and later on we will do a full watchface.

The main file we need to focus on is the '''clock.cpp''' file, it is what contains most of the data attributed to what we see on the watchface, including The time/day characters, the battery and bluetooth icons, and also pedometer count...

so everything we will be doing in the basic modifications is purely messing with this single file.

==Labels==
===What are labels?===
Labels are considered as "elemental" parts that make up a screen's Text-based UI by the LVGL library...
Each label is also considered as an "object" or "obj" and can be manipulated, by changing the data attributed with the "obj", for example, position, internal data like the strings/text etc.
when can change what the label shows and where it shows it...

===Modifying label data===
let's observe something small like the word "BPM" near the bottom of the watch face...
[[file:PineTimeCustom-1.png|right|200px]]

If we take a look at the source file of the watchface, (a.k.a the clock.cpp file)
we can observe that these particular lines are what attributes to the word "BPM being displayed...
heartbeatBpm = lv_label_create(lv_scr_act(), NULL);
lv_label_set_text(heartbeatBpm, "BPM");

we can modify the text inside the quotes and replace the word 'BPM' between those quotes to something like 'LOVE'
and the result after compiling the firmware again with the changes and flashing it to the watch would be that the text changes on the watch face and displays 'LOVE' inplace of 'BPM'...

If this happened correctly, then you have successfully made a custom new watchface! Now we can do something a bit more complex...

Now take for in instance the days of the week that we have on the bottom line with the date...

they are stored a "C array" which is basically multiple words separated by commas..
the date is in a format of '''<day of the week> <day> <Month> <year>'''

which in the source file is expressed as,
sprintf(dateStr, "%s %d %s %d", DayOfWeekToString(dayOfWeek), day, MonthToString(month), year);
lv_label_set_text(label_date, dateStr);

here,
%s %d %s %d
stores the print format of the variables, and

DayOfWeekToString(dayOfWeek), day, MonthToString(month), year
are the variables themselves...

Now,
if the date was a saturday 11/7/2020, you can observe that the date looks like
SATURDAY 11 JUL 2020
as seen in the above image (the one where we changed BPM to LOVE)

by modifying the format of the variables, we can change how those words are arranged, and add some extra characters if we like...
(there is a catch to the list of characters you can use however, but it will be discussed later...)

For example,

We modifying the format by adding a comma... "," in between the second "%s" and "%d" like this,
"%s %d %s, %d"
and changing that in the line...
sprintf(dateStr, "%s %d %s, %d", DayOfWeekToString(dayOfWeek), day, MonthToString(month), year);

we can make the date become...
SATURDAY 11 JUL, 2020

which means we now were able to modify how the text got display to make it a bit more nice...

but if you haven't noticed, the line containing the date is already full, meaning we will get some problems while displaying the date and causing it to wrap around,
making a single character go to the next line and look more like,

SATURDAY 11 JUL, 202
0

so why don't we shorten the characters present in the date from being "SATURDAY" to simply just "sat." (It will have the small period at the end, and is only 3 characters long)
I will also convert the months of the year from Capital to small letters...

for that look into the part where the days of the week of are stored as text,
and also while looking at it, we can solve another question, why was their two variables in the date format that looked like, DayOfWeekToString(dayOfWeek), and MonthToString(month) ?

It is because the system gives the date/ time as numbers (Monday-1, Tuesday-2 Wednesday-3 for the days, and 1-January, 2-February, 3-March ),
and so a function along with a C array is used to assign these numbers to Days/Months in text form as it is easier to read...

this is the Array containing the day of the week, (as text)
char const *Clock::DaysString[] = {
"",
"MONDAY",
"TUESDAY",
"WEDNESDAY",
"THURSDAY",
"FRIDAY",
"SATURDAY",
"SUNDAY"
};

and this Array stores the months of the year, (as text)
char const *Clock::MonthsString[] = {
"",
"JAN",
"FEB",
"MAR",
"APR",
"MAY",
"JUN",
"JUL",
"AUG",
"SEP",
"OCT",
"NOV",
"DEC"
};

here we can see that the days are stored in a full format as "SUNDAY", "MONDAY", "TUESDAY" etc.
we can change all of them to a shorter format like "sun.", "mon.", "tue.", to make it short and nice...
while doing so, we can even make the months use small letters as said before..

so the source file (clock.cpp) becomes,

(for the days of the week)
char const *Clock::DaysString[] = {
"",
"mon.",
"tue.",
"wed.",
"thu.",
"fri.",
"sat.",
"sun."
};

and

(for the months of the year)
char const *Clock::MonthsString[] = {
"",
"jan",
"feb",
"mar",
"apr",
"may",
"jun",
"jul",
"aug",
"sep",
"oct",
"nov",
"dec"
};

which means now our original date, saturday 11/7/2020 will become...
sat. 11 jul, 2020

you now know how to change the data present in a label object, and the format of it..,

Here is a fun idea you can try: you can even replace the days with whatever thing that tells you (or) reminds you the day of the week
(like the food served in the cafe, Monday/taco, Tuesday/burger, Wednesday/pasta etc.)

NOTE: when making the custom array, don't forget to leave a empty "" as the first element of the array,
This is because the date is given by the system in a natural numbers format (1,2,3...) rather than a zero-starting format (0,1,2,3...), which the C array uses to index...
so the C array indexes the days as ""-0, "Monday"-1, "Tuesday"-2 etc. and the months as ""-0, "January"-1, "February"-2 etc.)

===Label positioning===

The locational placement in LVGL is done on a cartesian plane,
where each object can have dynamic origin placement, and the Y-axis is inverted...
So going down is done with a positive Y-axis value and not negative as the it is by de-facto...

[[File:LVGL coord system.png|200px|thumb|right|LVGL coord system]]

The position of the various objects in clock.cpp are set by the line,
lv_obj_set_pos(<obj>, <new_x>, <new_y>)

and the top left corner is the Cartesian origin, aka coordinates (0,0)

this image can show you how to decide label placement for lv_obj_set_pos(...)

we use another function, that is more advanced that gives the positional alignment based on preset locations...
lv_obj_align(<text/obj>, <image/obj>, <location_parameter>, <new_x>, <new_y>);

the "<image/obj>" data is used for putting text beside other picture icons , and so if using only text based labels, we can substitute it with,
lv_scr_act() (or) NULL

'''<new_x>, <new_y>''' are the cartesian coordinates, '''<location parameter>''' is replaced by '''LV_ALIGN_<preset>''',
there will be a picture showing the presets below, and '''<text/obj>''' is your text label...

here, LV_ALIGN_<preset> sets the cartesian origin...

Label positioning based on alignment is both a simple and complicated thing to understand, so here I have given something you can refer to while modifying the position of the various labels and objects...

you can also refer here for LVGL's documentation of coordinate system https://docs.lvgl.io/v6/en/html/object-types/obj.html#coordinates

It is however recommended that you use the first method to set the location
lv_obj_set_pos(<obj>, <new_x>, <new_y>)
as it is simple and easier for beginners

Here is a small example.

Take the Label that tells the date,
In the source file (clock.cpp) it is this line,
lv_obj_align(label_date, lv_scr_act(), LV_ALIGN_IN_LEFT_MID, 0, 60);
by increasing the Value of the Y coordinate (60) to a higher value, we can bring the position of the Date downwards a bit away from the Time, and toward the Heartbeat count in the bottom row
here I will increase it to 80, so it becomes..
lv_obj_align(label_date, lv_scr_act(), LV_ALIGN_IN_LEFT_MID, 0, 80);

and now we have made some space up top..

now let's try something a bit complex,

Take the position argument for the label that tells you time...
here, in the source file (clock.cpp),
lv_obj_align(label_time, lv_scr_act(), LV_ALIGN_IN_LEFT_MID, 0, 0);

this line determines the position of the Label telling time, as seen in the image...

we modifying this, by changing the origin <preset> parameter (here it is LV_ALIGN_IN_LEFT_MID) to LV_ALIGN_IN_TOP_LEFT

you can alternatively swap the whole line to,
lv_obj_set_pos(label_time, 0, 0);

this makes the Time label/obj. to go to the top left corner...

but I will do something a little extra,
I will modify the label that store the data and Time format,
i.e this line,
sprintf(timeStr, "%c%c:%c%c", hoursChar[0],hoursChar[1],minutesChar[0], minutesChar[1]);

by removing the ":" colon in between the numbers, and replacing it with a Newline symbol "\n"
I change it to become,
sprintf(timeStr, "%c%c\n%c%c", hoursChar[0],hoursChar[1],minutesChar[0], minutesChar[1]);

this gives it a nice wrapped text format in the top corner, and gives us some space to play with in the side, for things like Pictures and icons, which we will do next..

If you have been able to do these things, you now have completed the 2nd part of the tutorial, and now know how to change and modify the position of labels..

==Using icons==
The LVGL library allows for the use of widgets known as "Images", In short it allows you to use small Icons like pictures with a small dedicated function,
However when this was attempted the first time we stumbled on some problems as LVGL v6 (used on the pinetime) is not much documented as the latest release (v7 as of August 2020)
but also the existing code was only documented for C not C++, after some painful attempts we were able to translate it into C++,

To bring images into Clock.cpp
you will need to do the following,

1. Have a small image that cannot exceed a maximum size of 240px x 240px (pinetime max resolution)

2. Use this Image converter (Thanks to LVGL) https://lvgl.io/tools/imageconverter
to convert your image to a C array and having the Color format as "True color" and the output format as "C array"
make sure to use something simple as the name we will be using "bitmap" as the name, but will also be referred as <name> for simplicity

Note: for example we shall use <name> = bitmap, but any simple word can be used, as long as it does not cause problems with system variables

===Image size considerations===
since the image will be using the flash directly, we need to be considerate about flash memory usage.

<picture_X> x <picture_Y> x 2
gives you the number of KB the image used in storage...

where, <picture_X> <picture_Y> are the dimensions of the image horizontally and vertically

for example,
if <picture_X>=80px <picture_Y>=64px
then,
total storage used = 80 x 60 x 2 = 10.24KB

please use the flash storage with consideration, when using other apps as well, excess usage of storage
might mean the Firmware will not compile... the limit to storage to about 400Kb for the user, the
firmware size must not exceed that...

==Preparing the image for inclusion as an icon==

Once you have your obtained your C array from the LVGL converter, you can take a look inside it to see all the different formats of your image,
try using something like Notepad++ or any of your favorite text editors to peek inside of it,

there will be 4 sets of Arrays inside it that look like,

#if LV_COLOR_DEPTH == 1 || LV_COLOR_DEPTH == 8
/*Pixel format: Red: 3 bit, Green: 3 bit, Blue: 2 bit*/
0x00, 0x00, 0x00,...
...0x00, 0x00, 0x00,
#endif

#if LV_COLOR_DEPTH == 16 && LV_COLOR_16_SWAP == 0
/*Pixel format: Red: 5 bit, Green: 6 bit, Blue: 5 bit*/
0x00, 0x00, 0x00,...
...0x00, 0x00, 0x00,
#endif

#if LV_COLOR_DEPTH == 16 && LV_COLOR_16_SWAP != 0
/*Pixel format: Red: 5 bit, Green: 6 bit, Blue: 5 bit BUT the 2 bytes are swapped*/
0x00, 0x00, 0x00,...
...0x00, 0x00, 0x00,
#endif

#if LV_COLOR_DEPTH == 32
/*Pixel format: Fix 0xFF: 8 bit, Red: 8 bit, Green: 8 bit, Blue: 8 bit*/
0x00, 0x00, 0x00,...
...0x00, 0x00, 0xff,
#endif
};

And another small bit of info we will need for later that looks like,

const lv_img_dsc_t bitmap = {
.header.always_zero = 0,
.header.w = 40,
.header.h = 40,
.data_size = 1600 * LV_COLOR_SIZE / 8,
.header.cf = LV_IMG_CF_TRUE_COLOR,
.data = bitmap_map,
};

NOTE: There are some header files at the top, which we can ignore...
===RGB565 image format===

The Pinetime uses a display that uses a 16 bit color space, also known as RGB565.

These 16 bit are assigned to RGB as 5 bits each for Red and Blue and 6 bits for Green, so 5+6+5=16 bits are required, so each pixel's color occupies 2 bytes of data,
and since 216 is equal to 65,536 it allows us to view 65,536 or 65k colors

The way it packs these bits is by converting the bits into 2x 4+4 bit hex-code, so for example,

if the color of a pixel in Binary is '''10110100 01011111''' (this color is approximately Lavender purple)

It is split as '''1011''' & '''0100''' for the first byte and '''0101''' & '''1111''' for the second byte
and so, converting the binary into Hex-code,

the two parts are '''0xB4''' and '''0xF5'''

These two parts in conjunction are used for determining the color of one pixel...

also from the binary, it is observed that,

The bits '''10110''' is used for Red, '''100010''' is used for green, and '''11111''' is used for blue.

===Flipping the bytes===
The LVGL library has a feature that allows you to flip the two bytes of the pixel, so if the two parts were, ...0xB4,0xF5,... ,it will change it to become, ...0xF5,0xB4,...

The reason for this is to allow the use of 8-bit SPI interfaces, but we do not require it, and if set with wrong parameter we could get problems with the color...

To make sure you are ready for the next step, make sure that inside your lvgl configuration file (located at '''src/libs/lv_conf.h''')

this parameter,
'''#define LV_COLOR_16_SWAP 1'''
is set to "1" as seen...

NOTE: if you haven't modified it or tampered with it with your Github fork, you shouldn't have a problem
as it is correct by default, and you can skip these steps

===Creating an Object from the Array===
To include the Icon, first Identify the Array you need to copy to the source (clock.cpp)

The one we require from it is the data below the tag that looks like,
#if LV_COLOR_DEPTH == 16 && LV_COLOR_16_SWAP != 0
/*Pixel format: Red: 5 bit, Green: 6 bit, Blue: 5 bit BUT the 2 bytes are swapped*/
0x00, 0x00, 0x00,...
...0x00, 0x00, 0x00,
#endif

from this copy the Data from the array alone...
I.e this part,
0x00, 0x00, 0x00,...
...0x00, 0x00, 0x00

(Make sure to not include the comma at the end or the #endif as the entire part is going to substitute a new array)

In clock.cpp, just below the header files and the Task creation part (I.e event_handler...),

static void event_handler(lv_obj_t * obj, lv_event_t event) {
Clock* screen = static_cast<Clock *>(obj->user_data);
screen->OnObjectEvent(obj, event);
}

create a name for the label with,
static lv_img_dsc_t <name>; // remember to replace <name> with the actual name you gave to your image while converting !

then below it create a array to hold the data with,
const uint8_t bitmap_map[] = { <data> }; // paste the array you copied from the conversion file we specified above...

so your Entire top region of declaration looks like,

#include <cstdio>
#include <libs/date/includes/date/date.h>
...
using namespace Pinetime::Applications::Screens;
extern lv_font_t jetbrains_mono_extrabold_compressed;
extern lv_font_t jetbrains_mono_bold_20;
extern lv_style_t* LabelBigStyle;
''' '''
static void event_handler(lv_obj_t * obj, lv_event_t event) {
Clock* screen = static_cast<Clock *>(obj->user_data);
screen->OnObjectEvent(obj, event);
}
''' '''
'''//Declare the descriptor here'''
static lv_img_dsc_t <name>;
'''//place the Image data here
const uint8_t bitmap_map[] = {0x00,0x00,0x00...
...0x00,0x00,0x00
};

'''note: Declaring variables outside a function like we did above is known as global scope declaration, this means the variable can be used by not just one function but the Entire code...'''

Then inside the
Clock::Clock(DisplayApp* app,...){...
region, (the watchface function)
You need to place a particular set of lines which LVGL uses to define the object declare the array as an Icon/Image, You can place this set of lines above label_time...

<name>.header.always_zero = 0; //Initialization
<name>.header.w = <picture_X>; // Setting the Width (or) Horizontal length of the image (number of px)
<name>.header.h = <picture_Y>; // Setting the Height (or) vertical length of the image (number of px)
<name>.data_size = <Hr_length> * <Vr_length> * LV_COLOR_SIZE / 8; //Allocation of memory for the image
<name>.header.cf = LV_IMG_CF_TRUE_COLOR; // Sets the color scheme for the image
<name>.data = <name>_map; // Maps the Image data to the Array
lv_obj_t *img_src = lv_img_create(lv_scr_act(), NULL); // Create an image object
lv_img_set_src(img_src, &<name>); // Set the created file as image (<name>)

again, make sure to replace <name> with the name you gave it during conversion!

Now that we have bought in the image data, we need to set the position, you can place this just below the lines we wrote for bringing in the image, It can be done with either,
lv_obj_set_pos(img_src, <x_pos, <y_pos>); // <x_pos>, <y_pos> are the coordinates of the cartesian plane
or,
lv_obj_align(img_src, lv_scr_act(), LV_ALIGN_<parameter>, <x_pos, <y_pos>);

If done correctly, you will now have a beautiful little Icon/Image in your Watch face,
Make sure that your Watch face can accommodate the Image by pushing the other labels farther away creating space for it...

We have provided a small template you can use for adding even a large image comfortably

If you have succeeded with this, you have completed part 3 of the tutorial.

=Using git to work on the firmware=
===Cloning the repository===
===Changing the code to add the image===
===Compiling the firmware===
==Testing the firmware==
===Installing the new firmware===

A holistic guide on how to install different firmware using various hardware programmers is available here: [[Reprogramming the PineTime]]. There's also the possibility of using OTA updating. ''//TODO: add that to the article!''

===Activating the firmware===
===How to troubleshoot===
==Conclusions==
==Next steps==
==More in-depth documentation==
==Thanks for the help==

PineTime Custom Watchface Tutorial

2020-09-27T06:47:24Z

Electr0lyte: /* Creating an Object from the Array */

=PineTime Custom Watchface Tutorial=

This is a tutorial to help new users create custom watchfaces based on the InfiniTime Firmware for Pinetime made by user JF002, thanks to him for its development...

We will explain some of the things we went through while creating some custom Watchfaces, so consider this as a log of experiments of sorts..

So stay tuned to it as it will be dynamically updated...

==What you need to start==
The entire building process will be done by GitHub, so all you need is a device which can give you a Github Web Client, a PC or tablet to give you enough screen space to review your code and a steady internet connection.

Since the compiling and file management is done by Github online, you have nothing else to worry about other than working with the files that display the watch face.

So with those things settled, let's start with the basics of a watchface.

Please remember that this is a wiki, so you can make an account and help us improve this page.

Please make sure not to unilaterally remove info though, but offer an alternative. If it is indeed a better way, in time your alternative will grow into the main text, and the latter info will be pruned.

==Overview==
The Firmware (also called InfiniTime) we will be working with is made with a programming language named '''C++''':[https://en.wikipedia.org/wiki/C%2B%2B]

Basic knowledge of C/C++ is required to to understand the advanced watch faces as that requires more complex code, but you can still do a some cool things without much knowledge of C++ programming, just some small edits to existing programs.

InfiniTime uses the '''LVGL''':[https://lvgl.io] graphics library to provide users with a simple and clean UI without overpowering the Nordic '''nRF52832''':[http://files.pine64.org/doc/datasheet/pinetime/nRF52832%20product%20brief.pdf] microcontroller which is the brain of the watch.

To get the watchface to work there are these basic steps. We will go over each step separately, so don't be daunted, all will become clear soon.

For now we will, modify the the existing watchface, change the positioning of the text labels, add an icon to an existing watchface, and later on we will do a full watchface.

The main file we need to focus on is the '''clock.cpp''' file, it is what contains most of the data attributed to what we see on the watchface, including The time/day characters, the battery and bluetooth icons, and also pedometer count...

so everything we will be doing in the basic modifications is purely messing with this single file.

==Labels==
===What are labels?===
Labels are considered as "elemental" parts that make up a screen's Text-based UI by the LVGL library...
Each label is also considered as an "object" or "obj" and can be manipulated, by changing the data attributed with the "obj", for example, position, internal data like the strings/text etc.
when can change what the label shows and where it shows it...

===Modifying label data===
let's observe something small like the word "BPM" near the bottom of the watch face...
[[file:PineTimeCustom-1.png|right|200px]]

If we take a look at the source file of the watchface, (a.k.a the clock.cpp file)
we can observe that these particular lines are what attributes to the word "BPM being displayed...
heartbeatBpm = lv_label_create(lv_scr_act(), NULL);
lv_label_set_text(heartbeatBpm, "BPM");

we can modify the text inside the quotes and replace the word 'BPM' between those quotes to something like 'LOVE'
and the result after compiling the firmware again with the changes and flashing it to the watch would be that the text changes on the watch face and displays 'LOVE' inplace of 'BPM'...

If this happened correctly, then you have successfully made a custom new watchface! Now we can do something a bit more complex...

Now take for in instance the days of the week that we have on the bottom line with the date...

they are stored a "C array" which is basically multiple words separated by commas..
the date is in a format of '''<day of the week> <day> <Month> <year>'''

which in the source file is expressed as,
sprintf(dateStr, "%s %d %s %d", DayOfWeekToString(dayOfWeek), day, MonthToString(month), year);
lv_label_set_text(label_date, dateStr);

here,
%s %d %s %d
stores the print format of the variables, and

DayOfWeekToString(dayOfWeek), day, MonthToString(month), year
are the variables themselves...

Now,
if the date was a saturday 11/7/2020, you can observe that the date looks like
SATURDAY 11 JUL 2020
as seen in the above image (the one where we changed BPM to LOVE)

by modifying the format of the variables, we can change how those words are arranged, and add some extra characters if we like...
(there is a catch to the list of characters you can use however, but it will be discussed later...)

For example,

We modifying the format by adding a comma... "," in between the second "%s" and "%d" like this,
"%s %d %s, %d"
and changing that in the line...
sprintf(dateStr, "%s %d %s, %d", DayOfWeekToString(dayOfWeek), day, MonthToString(month), year);

we can make the date become...
SATURDAY 11 JUL, 2020

which means we now were able to modify how the text got display to make it a bit more nice...

but if you haven't noticed, the line containing the date is already full, meaning we will get some problems while displaying the date and causing it to wrap around,
making a single character go to the next line and look more like,

SATURDAY 11 JUL, 202
0

so why don't we shorten the characters present in the date from being "SATURDAY" to simply just "sat." (It will have the small period at the end, and is only 3 characters long)
I will also convert the months of the year from Capital to small letters...

for that look into the part where the days of the week of are stored as text,
and also while looking at it, we can solve another question, why was their two variables in the date format that looked like, DayOfWeekToString(dayOfWeek), and MonthToString(month) ?

It is because the system gives the date/ time as numbers (Monday-1, Tuesday-2 Wednesday-3 for the days, and 1-January, 2-February, 3-March ),
and so a function along with a C array is used to assign these numbers to Days/Months in text form as it is easier to read...

this is the Array containing the day of the week, (as text)
char const *Clock::DaysString[] = {
"",
"MONDAY",
"TUESDAY",
"WEDNESDAY",
"THURSDAY",
"FRIDAY",
"SATURDAY",
"SUNDAY"
};

and this Array stores the months of the year, (as text)
char const *Clock::MonthsString[] = {
"",
"JAN",
"FEB",
"MAR",
"APR",
"MAY",
"JUN",
"JUL",
"AUG",
"SEP",
"OCT",
"NOV",
"DEC"
};

here we can see that the days are stored in a full format as "SUNDAY", "MONDAY", "TUESDAY" etc.
we can change all of them to a shorter format like "sun.", "mon.", "tue.", to make it short and nice...
while doing so, we can even make the months use small letters as said before..

so the source file (clock.cpp) becomes,

(for the days of the week)
char const *Clock::DaysString[] = {
"",
"mon.",
"tue.",
"wed.",
"thu.",
"fri.",
"sat.",
"sun."
};

and

(for the months of the year)
char const *Clock::MonthsString[] = {
"",
"jan",
"feb",
"mar",
"apr",
"may",
"jun",
"jul",
"aug",
"sep",
"oct",
"nov",
"dec"
};

which means now our original date, saturday 11/7/2020 will become...
sat. 11 jul, 2020

you now know how to change the data present in a label object, and the format of it..,

Here is a fun idea you can try: you can even replace the days with whatever thing that tells you (or) reminds you the day of the week
(like the food served in the cafe, Monday/taco, Tuesday/burger, Wednesday/pasta etc.)

NOTE: when making the custom array, don't forget to leave a empty "" as the first element of the array,
This is because the date is given by the system in a natural numbers format (1,2,3...) rather than a zero-starting format (0,1,2,3...), which the C array uses to index...
so the C array indexes the days as ""-0, "Monday"-1, "Tuesday"-2 etc. and the months as ""-0, "January"-1, "February"-2 etc.)

===Label positioning===

The locational placement in LVGL is done on a cartesian plane,
where each object can have dynamic origin placement, and the Y-axis is inverted...
So going down is done with a positive Y-axis value and not negative as the it is by de-facto...

[[File:LVGL coord system.png|200px|thumb|right|LVGL coord system]]

The position of the various objects in clock.cpp are set by the line,
lv_obj_set_pos(<obj>, <new_x>, <new_y>)

and the top left corner is the Cartesian origin, aka coordinates (0,0)

this image can show you how to decide label placement for lv_obj_set_pos(...)

we use another function, that is more advanced that gives the positional alignment based on preset locations...
lv_obj_align(<text/obj>, <image/obj>, <location_parameter>, <new_x>, <new_y>);

the "<image/obj>" data is used for putting text beside other picture icons , and so if using only text based labels, we can substitute it with,
lv_scr_act() (or) NULL

'''<new_x>, <new_y>''' are the cartesian coordinates, '''<location parameter>''' is replaced by '''LV_ALIGN_<preset>''',
there will be a picture showing the presets below, and '''<text/obj>''' is your text label...

here, LV_ALIGN_<preset> sets the cartesian origin...

Label positioning based on alignment is both a simple and complicated thing to understand, so here I have given something you can refer to while modifying the position of the various labels and objects...

you can also refer here for LVGL's documentation of coordinate system https://docs.lvgl.io/v6/en/html/object-types/obj.html#coordinates

It is however recommended that you use the first method to set the location
lv_obj_set_pos(<obj>, <new_x>, <new_y>)
as it is simple and easier for beginners

Here is a small example.

Take the Label that tells the date,
In the source file (clock.cpp) it is this line,
lv_obj_align(label_date, lv_scr_act(), LV_ALIGN_IN_LEFT_MID, 0, 60);
by increasing the Value of the Y coordinate (60) to a higher value, we can bring the position of the Date downwards a bit away from the Time, and toward the Heartbeat count in the bottom row
here I will increase it to 80, so it becomes..
lv_obj_align(label_date, lv_scr_act(), LV_ALIGN_IN_LEFT_MID, 0, 80);

and now we have made some space up top..

now let's try something a bit complex,

Take the position argument for the label that tells you time...
here, in the source file (clock.cpp),
lv_obj_align(label_time, lv_scr_act(), LV_ALIGN_IN_LEFT_MID, 0, 0);

this line determines the position of the Label telling time, as seen in the image...

we modifying this, by changing the origin <preset> parameter (here it is LV_ALIGN_IN_LEFT_MID) to LV_ALIGN_IN_TOP_LEFT

you can alternatively swap the whole line to,
lv_obj_set_pos(label_time, 0, 0);

this makes the Time label/obj. to go to the top left corner...

but I will do something a little extra,
I will modify the label that store the data and Time format,
i.e this line,
sprintf(timeStr, "%c%c:%c%c", hoursChar[0],hoursChar[1],minutesChar[0], minutesChar[1]);

by removing the ":" colon in between the numbers, and replacing it with a Newline symbol "\n"
I change it to become,
sprintf(timeStr, "%c%c\n%c%c", hoursChar[0],hoursChar[1],minutesChar[0], minutesChar[1]);

this gives it a nice wrapped text format in the top corner, and gives us some space to play with in the side, for things like Pictures and icons, which we will do next..

If you have been able to do these things, you now have completed the 2nd part of the tutorial, and now know how to change and modify the position of labels..

==Using icons==
The LVGL library allows for the use of widgets known as "Images", In short it allows you to use small Icons like pictures with a small dedicated function,
However when this was attempted the first time we stumbled on some problems as LVGL v6 (used on the pinetime) is not much documented as the latest release (v7 as of August 2020)
but also the existing code was only documented for C not C++, after some painful attempts we were able to translate it into C++,

To bring images into Clock.cpp
you will need to do the following,

1. Have a small image that cannot exceed a maximum size of 240px x 240px (pinetime max resolution)

2. Use this Image converter (Thanks to LVGL) https://lvgl.io/tools/imageconverter
to convert your image to a C array and having the Color format as "True color" and the output format as "C array"
make sure to use something simple as the name we will be using "bitmap" as the name, but will also be referred as <name> for simplicity

Note: for example we shall use <name> = bitmap, but any simple word can be used, as long as it does not cause problems with system variables

===Image size considerations===
since the image will be using the flash directly, we need to be considerate about flash memory usage.

<picture_X> x <picture_Y> x 2
gives you the number of KB the image used in storage...

where, <picture_X> <picture_Y> are the dimensions of the image horizontally and vertically

for example,
if <picture_X>=80px <picture_Y>=64px
then,
total storage used = 80 x 60 x 2 = 10.24KB

please use the flash storage with consideration, when using other apps as well, excess usage of storage
might mean the Firmware will not compile... the limit to storage to about 400Kb for the user, the
firmware size must not exceed that...

==Preparing the image for inclusion as an icon==

Once you have your obtained your C array from the LVGL converter, you can take a look inside it to see all the different formats of your image,
try using something like Notepad++ or any of your favorite text editors to peek inside of it,

there will be 4 sets of Arrays inside it that look like,

#if LV_COLOR_DEPTH == 1 || LV_COLOR_DEPTH == 8
/*Pixel format: Red: 3 bit, Green: 3 bit, Blue: 2 bit*/
0x00, 0x00, 0x00,...
...0x00, 0x00, 0x00,
#endif

#if LV_COLOR_DEPTH == 16 && LV_COLOR_16_SWAP == 0
/*Pixel format: Red: 5 bit, Green: 6 bit, Blue: 5 bit*/
0x00, 0x00, 0x00,...
...0x00, 0x00, 0x00,
#endif

#if LV_COLOR_DEPTH == 16 && LV_COLOR_16_SWAP != 0
/*Pixel format: Red: 5 bit, Green: 6 bit, Blue: 5 bit BUT the 2 bytes are swapped*/
0x00, 0x00, 0x00,...
...0x00, 0x00, 0x00,
#endif

#if LV_COLOR_DEPTH == 32
/*Pixel format: Fix 0xFF: 8 bit, Red: 8 bit, Green: 8 bit, Blue: 8 bit*/
0x00, 0x00, 0x00,...
...0x00, 0x00, 0xff,
#endif
};

And another small bit of info we will need for later that looks like,

const lv_img_dsc_t bitmap = {
.header.always_zero = 0,
.header.w = 40,
.header.h = 40,
.data_size = 1600 * LV_COLOR_SIZE / 8,
.header.cf = LV_IMG_CF_TRUE_COLOR,
.data = bitmap_map,
};

NOTE: There are some header files at the top, which we can ignore...
===RGB565 image format===

The Pinetime uses a display that uses a 16 bit color space, also known as RGB565.

These 16 bit are assigned to RGB as 5 bits each for Red and Blue and 6 bits for Green, so 5+6+5=16 bits are required, so each pixel's color occupies 2 bytes of data,
and since 216 is equal to 65,536 it allows us to view 65,536 or 65k colors

The way it packs these bits is by converting the bits into 2x 4+4 bit hex-code, so for example,

if the color of a pixel in Binary is '''10110100 01011111''' (this color is approximately Lavender purple)

It is split as '''1011''' & '''0100''' for the first byte and '''0101''' & '''1111''' for the second byte
and so, converting the binary into Hex-code,

the two parts are '''0xB4''' and '''0xF5'''

These two parts in conjunction are used for determining the color of one pixel...

also from the binary, it is observed that,

The bits '''10110''' is used for Red, '''100010''' is used for green, and '''11111''' is used for blue.

===Flipping the bytes===
The LVGL library has a feature that allows you to flip the two bytes of the pixel, so if the two parts were, ...0xB4,0xF5,... ,it will change it to become, ...0xF5,0xB4,...

The reason for this is to allow the use of 8-bit SPI interfaces, but we do not require it, and if set with wrong parameter we could get problems with the color...

To make sure you are ready for the next step, make sure that inside your lvgl configuration file (located at '''src/libs/lv_conf.h''')

this parameter,
'''#define LV_COLOR_16_SWAP 1'''
is set to "1" as seen...

NOTE: if you haven't modified it or tampered with it with your Github fork, you shouldn't have a problem
as it is correct by default, and you can skip these steps

===Creating an Object from the Array===
To include the Icon, first Identify the Array you need to copy to the source (clock.cpp)

The one we require from it is the data below the tag that looks like,
#if LV_COLOR_DEPTH == 16 && LV_COLOR_16_SWAP != 0
/*Pixel format: Red: 5 bit, Green: 6 bit, Blue: 5 bit BUT the 2 bytes are swapped*/
0x00, 0x00, 0x00,...
...0x00, 0x00, 0x00,
#endif

from this copy the Data from the array alone...
I.e this part,
0x00, 0x00, 0x00,...
...0x00, 0x00, 0x00

(Make sure to not include the comma at the end or the #endif as the entire part is going to substitute a new array)

In clock.cpp, just below the header files and the Task creation part (I.e event_handler...),

static void event_handler(lv_obj_t * obj, lv_event_t event) {
Clock* screen = static_cast<Clock *>(obj->user_data);
screen->OnObjectEvent(obj, event);
}

create a name for the label with,
static lv_img_dsc_t <name>; // remember to replace <name> with the actual name you gave to your image while converting !

then below it create a array to hold the data with,
const uint8_t bitmap_map[] = {<data>}; // paste the array you copied from the conversion file we specified above...

so your Entire top region of declaration looks like,

#include <cstdio>
#include <libs/date/includes/date/date.h>
...
using namespace Pinetime::Applications::Screens;
extern lv_font_t jetbrains_mono_extrabold_compressed;
extern lv_font_t jetbrains_mono_bold_20;
extern lv_style_t* LabelBigStyle;
''' '''
static void event_handler(lv_obj_t * obj, lv_event_t event) {
Clock* screen = static_cast<Clock *>(obj->user_data);
screen->OnObjectEvent(obj, event);
}
''' '''
'''//Declare the descriptor here'''
static lv_img_dsc_t <name>;
'''//place the Image data here
const uint8_t bitmap_map[] = {0x00,0x00,0x00...
...0x00,0x00,0x00
};

'''note: Declaring variables outside a function like we did above is known as global scope declaration, this means the variable can be used by not just one function but the Entire code...'''

Then inside the
Clock::Clock(DisplayApp* app,...){...
region, (the watchface function)
You need to place a particular set of lines which LVGL uses to define the object declare the array as an Icon/Image, You can place this set of lines above label_time...

<name>.header.always_zero = 0; //Initialization
<name>.header.w = <picture_X>; // Setting the Width (or) Horizontal length of the image (number of px)
<name>.header.h = <picture_Y>; // Setting the Height (or) vertical length of the image (number of px)
<name>.data_size = <Hr_length> * <Vr_length> * LV_COLOR_SIZE / 8; //Allocation of memory for the image
<name>.header.cf = LV_IMG_CF_TRUE_COLOR; // Sets the color scheme for the image
<name>.data = <name>_map; // Maps the Image data to the Array
lv_obj_t *img_src = lv_img_create(lv_scr_act(), NULL); // Create an image object
lv_img_set_src(img_src, &<name>); // Set the created file as image (<name>)

again, make sure to replace <name> with the name you gave it during conversion!

Now that we have bought in the image data, we need to set the position, you can place this just below the lines we wrote for bringing in the image, It can be done with either,
lv_obj_set_pos(img_src, <x_pos, <y_pos>); // <x_pos>, <y_pos> are the coordinates of the cartesian plane
or,
lv_obj_align(img_src, lv_scr_act(), LV_ALIGN_<parameter>, <x_pos, <y_pos>);

If done correctly, you will now have a beautiful little Icon/Image in your Watch face,
Make sure that your Watch face can accommodate the Image by pushing the other labels farther away creating space for it...

We have provided a small template you can use for adding even a large image comfortably

If you have succeeded with this, you have completed part 3 of the tutorial.

=Using git to work on the firmware=
===Cloning the repository===
===Changing the code to add the image===
===Compiling the firmware===
==Testing the firmware==
===Installing the new firmware===

A holistic guide on how to install different firmware using various hardware programmers is available here: [[Reprogramming the PineTime]]. There's also the possibility of using OTA updating. ''//TODO: add that to the article!''

===Activating the firmware===
===How to troubleshoot===
==Conclusions==
==Next steps==
==More in-depth documentation==
==Thanks for the help==

PineTime Custom Watchface Tutorial

2020-09-27T03:55:48Z

Electr0lyte: /* Creating an Object from the Array */

=PineTime Custom Watchface Tutorial=

This is a tutorial to help new users create custom watchfaces based on the InfiniTime Firmware for Pinetime made by user JF002, thanks to him for its development...

We will explain some of the things we went through while creating some custom Watchfaces, so consider this as a log of experiments of sorts..

So stay tuned to it as it will be dynamically updated...

==What you need to start==
The entire building process will be done by GitHub, so all you need is a device which can give you a Github Web Client, a PC or tablet to give you enough screen space to review your code and a steady internet connection.

Since the compiling and file management is done by Github online, you have nothing else to worry about other than working with the files that display the watch face.

So with those things settled, let's start with the basics of a watchface.

Please remember that this is a wiki, so you can make an account and help us improve this page.

Please make sure not to unilaterally remove info though, but offer an alternative. If it is indeed a better way, in time your alternative will grow into the main text, and the latter info will be pruned.

==Overview==
The Firmware (also called InfiniTime) we will be working with is made with a programming language named '''C++''':[https://en.wikipedia.org/wiki/C%2B%2B]

Basic knowledge of C/C++ is required to to understand the advanced watch faces as that requires more complex code, but you can still do a some cool things without much knowledge of C++ programming, just some small edits to existing programs.

InfiniTime uses the '''LVGL''':[https://lvgl.io] graphics library to provide users with a simple and clean UI without overpowering the Nordic '''nRF52832''':[http://files.pine64.org/doc/datasheet/pinetime/nRF52832%20product%20brief.pdf] microcontroller which is the brain of the watch.

To get the watchface to work there are these basic steps. We will go over each step separately, so don't be daunted, all will become clear soon.

For now we will, modify the the existing watchface, change the positioning of the text labels, add an icon to an existing watchface, and later on we will do a full watchface.

The main file we need to focus on is the '''clock.cpp''' file, it is what contains most of the data attributed to what we see on the watchface, including The time/day characters, the battery and bluetooth icons, and also pedometer count...

so everything we will be doing in the basic modifications is purely messing with this single file.

==Labels==
===What are labels?===
Labels are considered as "elemental" parts that make up a screen's Text-based UI by the LVGL library...
Each label is also considered as an "object" or "obj" and can be manipulated, by changing the data attributed with the "obj", for example, position, internal data like the strings/text etc.
when can change what the label shows and where it shows it...

===Modifying label data===
let's observe something small like the word "BPM" near the bottom of the watch face...
[[file:PineTimeCustom-1.png|right|200px]]

If we take a look at the source file of the watchface, (a.k.a the clock.cpp file)
we can observe that these particular lines are what attributes to the word "BPM being displayed...
heartbeatBpm = lv_label_create(lv_scr_act(), NULL);
lv_label_set_text(heartbeatBpm, "BPM");

we can modify the text inside the quotes and replace the word 'BPM' between those quotes to something like 'LOVE'
and the result after compiling the firmware again with the changes and flashing it to the watch would be that the text changes on the watch face and displays 'LOVE' inplace of 'BPM'...

If this happened correctly, then you have successfully made a custom new watchface! Now we can do something a bit more complex...

Now take for in instance the days of the week that we have on the bottom line with the date...

they are stored a "C array" which is basically multiple words separated by commas..
the date is in a format of '''<day of the week> <day> <Month> <year>'''

which in the source file is expressed as,
sprintf(dateStr, "%s %d %s %d", DayOfWeekToString(dayOfWeek), day, MonthToString(month), year);
lv_label_set_text(label_date, dateStr);

here,
%s %d %s %d
stores the print format of the variables, and

DayOfWeekToString(dayOfWeek), day, MonthToString(month), year
are the variables themselves...

Now,
if the date was a saturday 11/7/2020, you can observe that the date looks like
SATURDAY 11 JUL 2020
as seen in the above image (the one where we changed BPM to LOVE)

by modifying the format of the variables, we can change how those words are arranged, and add some extra characters if we like...
(there is a catch to the list of characters you can use however, but it will be discussed later...)

For example,

We modifying the format by adding a comma... "," in between the second "%s" and "%d" like this,
"%s %d %s, %d"
and changing that in the line...
sprintf(dateStr, "%s %d %s, %d", DayOfWeekToString(dayOfWeek), day, MonthToString(month), year);

we can make the date become...
SATURDAY 11 JUL, 2020

which means we now were able to modify how the text got display to make it a bit more nice...

but if you haven't noticed, the line containing the date is already full, meaning we will get some problems while displaying the date and causing it to wrap around,
making a single character go to the next line and look more like,

SATURDAY 11 JUL, 202
0

so why don't we shorten the characters present in the date from being "SATURDAY" to simply just "sat." (It will have the small period at the end, and is only 3 characters long)
I will also convert the months of the year from Capital to small letters...

for that look into the part where the days of the week of are stored as text,
and also while looking at it, we can solve another question, why was their two variables in the date format that looked like, DayOfWeekToString(dayOfWeek), and MonthToString(month) ?

It is because the system gives the date/ time as numbers (Monday-1, Tuesday-2 Wednesday-3 for the days, and 1-January, 2-February, 3-March ),
and so a function along with a C array is used to assign these numbers to Days/Months in text form as it is easier to read...

this is the Array containing the day of the week, (as text)
char const *Clock::DaysString[] = {
"",
"MONDAY",
"TUESDAY",
"WEDNESDAY",
"THURSDAY",
"FRIDAY",
"SATURDAY",
"SUNDAY"
};

and this Array stores the months of the year, (as text)
char const *Clock::MonthsString[] = {
"",
"JAN",
"FEB",
"MAR",
"APR",
"MAY",
"JUN",
"JUL",
"AUG",
"SEP",
"OCT",
"NOV",
"DEC"
};

here we can see that the days are stored in a full format as "SUNDAY", "MONDAY", "TUESDAY" etc.
we can change all of them to a shorter format like "sun.", "mon.", "tue.", to make it short and nice...
while doing so, we can even make the months use small letters as said before..

so the source file (clock.cpp) becomes,

(for the days of the week)
char const *Clock::DaysString[] = {
"",
"mon.",
"tue.",
"wed.",
"thu.",
"fri.",
"sat.",
"sun."
};

and

(for the months of the year)
char const *Clock::MonthsString[] = {
"",
"jan",
"feb",
"mar",
"apr",
"may",
"jun",
"jul",
"aug",
"sep",
"oct",
"nov",
"dec"
};

which means now our original date, saturday 11/7/2020 will become...
sat. 11 jul, 2020

you now know how to change the data present in a label object, and the format of it..,

Here is a fun idea you can try: you can even replace the days with whatever thing that tells you (or) reminds you the day of the week
(like the food served in the cafe, Monday/taco, Tuesday/burger, Wednesday/pasta etc.)

NOTE: when making the custom array, don't forget to leave a empty "" as the first element of the array,
This is because the date is given by the system in a natural numbers format (1,2,3...) rather than a zero-starting format (0,1,2,3...), which the C array uses to index...
so the C array indexes the days as ""-0, "Monday"-1, "Tuesday"-2 etc. and the months as ""-0, "January"-1, "February"-2 etc.)

===Label positioning===

The locational placement in LVGL is done on a cartesian plane,
where each object can have dynamic origin placement, and the Y-axis is inverted...
So going down is done with a positive Y-axis value and not negative as the it is by de-facto...

[[File:LVGL coord system.png|200px|thumb|right|LVGL coord system]]

The position of the various objects in clock.cpp are set by the line,
lv_obj_set_pos(<obj>, <new_x>, <new_y>)

and the top left corner is the Cartesian origin, aka coordinates (0,0)

this image can show you how to decide label placement for lv_obj_set_pos(...)

we use another function, that is more advanced that gives the positional alignment based on preset locations...
lv_obj_align(<text/obj>, <image/obj>, <location_parameter>, <new_x>, <new_y>);

the "<image/obj>" data is used for putting text beside other picture icons , and so if using only text based labels, we can substitute it with,
lv_scr_act() (or) NULL

'''<new_x>, <new_y>''' are the cartesian coordinates, '''<location parameter>''' is replaced by '''LV_ALIGN_<preset>''',
there will be a picture showing the presets below, and '''<text/obj>''' is your text label...

here, LV_ALIGN_<preset> sets the cartesian origin...

Label positioning based on alignment is both a simple and complicated thing to understand, so here I have given something you can refer to while modifying the position of the various labels and objects...

you can also refer here for LVGL's documentation of coordinate system https://docs.lvgl.io/v6/en/html/object-types/obj.html#coordinates

It is however recommended that you use the first method to set the location
lv_obj_set_pos(<obj>, <new_x>, <new_y>)
as it is simple and easier for beginners

Here is a small example.

Take the Label that tells the date,
In the source file (clock.cpp) it is this line,
lv_obj_align(label_date, lv_scr_act(), LV_ALIGN_IN_LEFT_MID, 0, 60);
by increasing the Value of the Y coordinate (60) to a higher value, we can bring the position of the Date downwards a bit away from the Time, and toward the Heartbeat count in the bottom row
here I will increase it to 80, so it becomes..
lv_obj_align(label_date, lv_scr_act(), LV_ALIGN_IN_LEFT_MID, 0, 80);

and now we have made some space up top..

now let's try something a bit complex,

Take the position argument for the label that tells you time...
here, in the source file (clock.cpp),
lv_obj_align(label_time, lv_scr_act(), LV_ALIGN_IN_LEFT_MID, 0, 0);

this line determines the position of the Label telling time, as seen in the image...

we modifying this, by changing the origin <preset> parameter (here it is LV_ALIGN_IN_LEFT_MID) to LV_ALIGN_IN_TOP_LEFT

you can alternatively swap the whole line to,
lv_obj_set_pos(label_time, 0, 0);

this makes the Time label/obj. to go to the top left corner...

but I will do something a little extra,
I will modify the label that store the data and Time format,
i.e this line,
sprintf(timeStr, "%c%c:%c%c", hoursChar[0],hoursChar[1],minutesChar[0], minutesChar[1]);

by removing the ":" colon in between the numbers, and replacing it with a Newline symbol "\n"
I change it to become,
sprintf(timeStr, "%c%c\n%c%c", hoursChar[0],hoursChar[1],minutesChar[0], minutesChar[1]);

this gives it a nice wrapped text format in the top corner, and gives us some space to play with in the side, for things like Pictures and icons, which we will do next..

If you have been able to do these things, you now have completed the 2nd part of the tutorial, and now know how to change and modify the position of labels..

==Using icons==
The LVGL library allows for the use of widgets known as "Images", In short it allows you to use small Icons like pictures with a small dedicated function,
However when this was attempted the first time we stumbled on some problems as LVGL v6 (used on the pinetime) is not much documented as the latest release (v7 as of August 2020)
but also the existing code was only documented for C not C++, after some painful attempts we were able to translate it into C++,

To bring images into Clock.cpp
you will need to do the following,

1. Have a small image that cannot exceed a maximum size of 240px x 240px (pinetime max resolution)

2. Use this Image converter (Thanks to LVGL) https://lvgl.io/tools/imageconverter
to convert your image to a C array and having the Color format as "True color" and the output format as "C array"
make sure to use something simple as the name we will be using "bitmap" as the name, but will also be referred as <name> for simplicity

Note: for example we shall use <name> = bitmap, but any simple word can be used, as long as it does not cause problems with system variables

===Image size considerations===
since the image will be using the flash directly, we need to be considerate about flash memory usage.

<picture_X> x <picture_Y> x 2
gives you the number of KB the image used in storage...

where, <picture_X> <picture_Y> are the dimensions of the image horizontally and vertically

for example,
if <picture_X>=80px <picture_Y>=64px
then,
total storage used = 80 x 60 x 2 = 10.24KB

please use the flash storage with consideration, when using other apps as well, excess usage of storage
might mean the Firmware will not compile... the limit to storage to about 400Kb for the user, the
firmware size must not exceed that...

==Preparing the image for inclusion as an icon==

Once you have your obtained your C array from the LVGL converter, you can take a look inside it to see all the different formats of your image,
try using something like Notepad++ or any of your favorite text editors to peek inside of it,

there will be 4 sets of Arrays inside it that look like,

#if LV_COLOR_DEPTH == 1 || LV_COLOR_DEPTH == 8
/*Pixel format: Red: 3 bit, Green: 3 bit, Blue: 2 bit*/
0x00, 0x00, 0x00,...
...0x00, 0x00, 0x00,
#endif

#if LV_COLOR_DEPTH == 16 && LV_COLOR_16_SWAP == 0
/*Pixel format: Red: 5 bit, Green: 6 bit, Blue: 5 bit*/
0x00, 0x00, 0x00,...
...0x00, 0x00, 0x00,
#endif

#if LV_COLOR_DEPTH == 16 && LV_COLOR_16_SWAP != 0
/*Pixel format: Red: 5 bit, Green: 6 bit, Blue: 5 bit BUT the 2 bytes are swapped*/
0x00, 0x00, 0x00,...
...0x00, 0x00, 0x00,
#endif

#if LV_COLOR_DEPTH == 32
/*Pixel format: Fix 0xFF: 8 bit, Red: 8 bit, Green: 8 bit, Blue: 8 bit*/
0x00, 0x00, 0x00,...
...0x00, 0x00, 0xff,
#endif
};

And another small bit of info we will need for later that looks like,

const lv_img_dsc_t bitmap = {
.header.always_zero = 0,
.header.w = 40,
.header.h = 40,
.data_size = 1600 * LV_COLOR_SIZE / 8,
.header.cf = LV_IMG_CF_TRUE_COLOR,
.data = bitmap_map,
};

NOTE: There are some header files at the top, which we can ignore...
===RGB565 image format===

The Pinetime uses a display that uses a 16 bit color space, also known as RGB565.

These 16 bit are assigned to RGB as 5 bits each for Red and Blue and 6 bits for Green, so 5+6+5=16 bits are required, so each pixel's color occupies 2 bytes of data,
and since 216 is equal to 65,536 it allows us to view 65,536 or 65k colors

The way it packs these bits is by converting the bits into 2x 4+4 bit hex-code, so for example,

if the color of a pixel in Binary is '''10110100 01011111''' (this color is approximately Lavender purple)

It is split as '''1011''' & '''0100''' for the first byte and '''0101''' & '''1111''' for the second byte
and so, converting the binary into Hex-code,

the two parts are '''0xB4''' and '''0xF5'''

These two parts in conjunction are used for determining the color of one pixel...

also from the binary, it is observed that,

The bits '''10110''' is used for Red, '''100010''' is used for green, and '''11111''' is used for blue.

===Flipping the bytes===
The LVGL library has a feature that allows you to flip the two bytes of the pixel, so if the two parts were, ...0xB4,0xF5,... ,it will change it to become, ...0xF5,0xB4,...

The reason for this is to allow the use of 8-bit SPI interfaces, but we do not require it, and if set with wrong parameter we could get problems with the color...

To make sure you are ready for the next step, make sure that inside your lvgl configuration file (located at '''src/libs/lv_conf.h''')

this parameter,
'''#define LV_COLOR_16_SWAP 1'''
is set to "1" as seen...

NOTE: if you haven't modified it or tampered with it with your Github fork, you shouldn't have a problem
as it is correct by default, and you can skip these steps

===Creating an Object from the Array===
To include the Icon, first Identify the Array you need to copy to the source (clock.cpp)

The one we require from it is the data below the tag that looks like,
#if LV_COLOR_DEPTH == 16 && LV_COLOR_16_SWAP != 0
/*Pixel format: Red: 5 bit, Green: 6 bit, Blue: 5 bit BUT the 2 bytes are swapped*/
0x00, 0x00, 0x00,...
...0x00, 0x00, 0x00,
#endif

from this copy the Data from the array alone...
I.e this part,
0x00, 0x00, 0x00,...
...0x00, 0x00, 0x00

(Make sure to not include the comma at the end or the #endif as the entire part is going to substitute a new array)

In clock.cpp, just below the header files and the Task creation part (I.e event_handler...),
create a name for the label with,
static lv_img_dsc_t <name>; // remember to replace <name> with the actual name you gave to your image while converting !

then below it create a array to hold the data with,
const uint8_t bitmap_map[] = {<data>}; // paste the array you copied from the conversion file we specified above...

Then inside the Clock::Clock(DisplayApp* app,...){... region,
You need to place a particular set of lines which LVGL uses to define the object declare the array as an Icon/Image, You can place this set of lines above label_time...

<name>.header.always_zero = 0; //Initialization
<name>.header.w = <picture_X>; // Setting the Width (or) Horizontal length of the image (number of px)
<name>.header.h = <picture_Y>; // Setting the Height (or) vertical length of the image (number of px)
<name>.data_size = <Hr_length> * <Vr_length> * LV_COLOR_SIZE / 8; //Allocation of memory for the image
<name>.header.cf = LV_IMG_CF_TRUE_COLOR; // Sets the color scheme for the image
<name>.data = <name>_map; // Maps the Image data to the Array
lv_obj_t *img_src = lv_img_create(lv_scr_act(), NULL); // Create an image object
lv_img_set_src(img_src, &<name>); // Set the created file as image (<name>)

again, make sure to replace <name> with the name you gave it during conversion!

Now that we have bought in the image data, we need to set the position, you can place this just below the lines we wrote for bringing in the image, It can be done with either,
lv_obj_set_pos(img_src, <x_pos, <y_pos>); // <x_pos>, <y_pos> are the coordinates of the cartesian plane
or,
lv_obj_align(img_src, lv_scr_act(), LV_ALIGN_<parameter>, <x_pos, <y_pos>);

If done correctly, you will now have a beautiful little Icon/Image in your Watch face,
Make sure that your Watch face can accommodate the Image by pushing the other labels farther away creating space for it...

We have provided a small template you can use for adding even a large image comfortably

If you have succeeded with this, you have completed part 3 of the tutorial.

=Using git to work on the firmware=
===Cloning the repository===
===Changing the code to add the image===
===Compiling the firmware===
==Testing the firmware==
===Installing the new firmware===

A holistic guide on how to install different firmware using various hardware programmers is available here: [[Reprogramming the PineTime]]. There's also the possibility of using OTA updating. ''//TODO: add that to the article!''

===Activating the firmware===
===How to troubleshoot===
==Conclusions==
==Next steps==
==More in-depth documentation==
==Thanks for the help==

PineTime Custom Watchface Tutorial

2020-09-23T15:01:53Z

Electr0lyte: /* Label positioning */

=PineTime Custom Watchface Tutorial=

This is a tutorial to help new users create custom watchfaces based on the InfiniTime Firmware for Pinetime made by user JF002, thanks to him for its development...

We will explain some of the things we went through while creating some custom Watchfaces, so consider this as a log of experiments of sorts..

So stay tuned to it as it will be dynamically updated...

==What you need to start==
The entire building process will be done by GitHub, so all you need is a device which can give you a Github Web Client, a PC or tablet to give you enough screen space to review your code and a steady internet connection.

Since the compiling and file management is done by Github online, you have nothing else to worry about other than working with the files that display the watch face.

So with those things settled, let's start with the basics of a watchface.

Please remember that this is a wiki, so you can make an account and help us improve this page.

Please make sure not to unilaterally remove info though, but offer an alternative. If it is indeed a better way, in time your alternative will grow into the main text, and the latter info will be pruned.

==Overview==
The Firmware (also called InfiniTime) we will be working with is made with a programming language named '''C++''':[https://en.wikipedia.org/wiki/C%2B%2B]

Basic knowledge of C/C++ is required to to understand the advanced watch faces as that requires more complex code, but you can still do a some cool things without much knowledge of C++ programming, just some small edits to existing programs.

InfiniTime uses the '''LVGL''':[https://lvgl.io] graphics library to provide users with a simple and clean UI without overpowering the Nordic '''nRF52832''':[http://files.pine64.org/doc/datasheet/pinetime/nRF52832%20product%20brief.pdf] microcontroller which is the brain of the watch.

To get the watchface to work there are these basic steps. We will go over each step separately, so don't be daunted, all will become clear soon.

For now we will, modify the the existing watchface, change the positioning of the text labels, add an icon to an existing watchface, and later on we will do a full watchface.

The main file we need to focus on is the '''clock.cpp''' file, it is what contains most of the data attributed to what we see on the watchface, including The time/day characters, the battery and bluetooth icons, and also pedometer count...

so everything we will be doing in the basic modifications is purely messing with this single file.

==Labels==
===What are labels?===
Labels are considered as "elemental" parts that make up a screen's Text-based UI by the LVGL library...
Each label is also considered as an "object" or "obj" and can be manipulated, by changing the data attributed with the "obj", for example, position, internal data like the strings/text etc.
when can change what the label shows and where it shows it...

===Modifying label data===
let's observe something small like the word "BPM" near the bottom of the watch face...
[[file:PineTimeCustom-1.png|right|200px]]

If we take a look at the source file of the watchface, (a.k.a the clock.cpp file)
we can observe that these particular lines are what attributes to the word "BPM being displayed...
heartbeatBpm = lv_label_create(lv_scr_act(), NULL);
lv_label_set_text(heartbeatBpm, "BPM");

we can modify the text inside the quotes and replace the word 'BPM' between those quotes to something like 'LOVE'
and the result after compiling the firmware again with the changes and flashing it to the watch would be that the text changes on the watch face and displays 'LOVE' inplace of 'BPM'...

If this happened correctly, then you have successfully made a custom new watchface! Now we can do something a bit more complex...

Now take for in instance the days of the week that we have on the bottom line with the date...

they are stored a "C array" which is basically multiple words separated by commas..
the date is in a format of '''<day of the week> <day> <Month> <year>'''

which in the source file is expressed as,
sprintf(dateStr, "%s %d %s %d", DayOfWeekToString(dayOfWeek), day, MonthToString(month), year);
lv_label_set_text(label_date, dateStr);

here,
%s %d %s %d
stores the print format of the variables, and

DayOfWeekToString(dayOfWeek), day, MonthToString(month), year
are the variables themselves...

Now,
if the date was a saturday 11/7/2020, you can observe that the date looks like
SATURDAY 11 JUL 2020
as seen in the above image (the one where we changed BPM to LOVE)

by modifying the format of the variables, we can change how those words are arranged, and add some extra characters if we like...
(there is a catch to the list of characters you can use however, but it will be discussed later...)

For example,

We modifying the format by adding a comma... "," in between the second "%s" and "%d" like this,
"%s %d %s, %d"
and changing that in the line...
sprintf(dateStr, "%s %d %s, %d", DayOfWeekToString(dayOfWeek), day, MonthToString(month), year);

we can make the date become...
SATURDAY 11 JUL, 2020

which means we now were able to modify how the text got display to make it a bit more nice...

but if you haven't noticed, the line containing the date is already full, meaning we will get some problems while displaying the date and causing it to wrap around,
making a single character go to the next line and look more like,

SATURDAY 11 JUL, 202
0

so why don't we shorten the characters present in the date from being "SATURDAY" to simply just "sat." (It will have the small period at the end, and is only 3 characters long)
I will also convert the months of the year from Capital to small letters...

for that look into the part where the days of the week of are stored as text,
and also while looking at it, we can solve another question, why was their two variables in the date format that looked like, DayOfWeekToString(dayOfWeek), and MonthToString(month) ?

It is because the system gives the date/ time as numbers (Monday-1, Tuesday-2 Wednesday-3 for the days, and 1-January, 2-February, 3-March ),
and so a function along with a C array is used to assign these numbers to Days/Months in text form as it is easier to read...

this is the Array containing the day of the week, (as text)
char const *Clock::DaysString[] = {
"",
"MONDAY",
"TUESDAY",
"WEDNESDAY",
"THURSDAY",
"FRIDAY",
"SATURDAY",
"SUNDAY"
};

and this Array stores the months of the year, (as text)
char const *Clock::MonthsString[] = {
"",
"JAN",
"FEB",
"MAR",
"APR",
"MAY",
"JUN",
"JUL",
"AUG",
"SEP",
"OCT",
"NOV",
"DEC"
};

here we can see that the days are stored in a full format as "SUNDAY", "MONDAY", "TUESDAY" etc.
we can change all of them to a shorter format like "sun.", "mon.", "tue.", to make it short and nice...
while doing so, we can even make the months use small letters as said before..

so the source file (clock.cpp) becomes,

(for the days of the week)
char const *Clock::DaysString[] = {
"",
"mon.",
"tue.",
"wed.",
"thu.",
"fri.",
"sat.",
"sun."
};

and

(for the months of the year)
char const *Clock::MonthsString[] = {
"",
"jan",
"feb",
"mar",
"apr",
"may",
"jun",
"jul",
"aug",
"sep",
"oct",
"nov",
"dec"
};

which means now our original date, saturday 11/7/2020 will become...
sat. 11 jul, 2020

you now know how to change the data present in a label object, and the format of it..,

Here is a fun idea you can try: you can even replace the days with whatever thing that tells you (or) reminds you the day of the week
(like the food served in the cafe, Monday/taco, Tuesday/burger, Wednesday/pasta etc.)

NOTE: when making the custom array, don't forget to leave a empty "" as the first element of the array,
This is because the date is given by the system in a natural numbers format (1,2,3...) rather than a zero-starting format (0,1,2,3...), which the C array uses to index...
so the C array indexes the days as ""-0, "Monday"-1, "Tuesday"-2 etc. and the months as ""-0, "January"-1, "February"-2 etc.)

===Label positioning===

The locational placement in LVGL is done on a cartesian plane,
where each object can have dynamic origin placement, and the Y-axis is inverted...
So going down is done with a positive Y-axis value and not negative as the it is by de-facto...

[[File:LVGL coord system.png|200px|thumb|right|LVGL coord system]]

The position of the various objects in clock.cpp are set by the line,
lv_obj_set_pos(<obj>, <new_x>, <new_y>)

and the top left corner is the Cartesian origin, aka coordinates (0,0)

this image can show you how to decide label placement for lv_obj_set_pos(...)

we use another function, that is more advanced that gives the positional alignment based on preset locations...
lv_obj_align(<text/obj>, <image/obj>, <location_parameter>, <new_x>, <new_y>);

the "<image/obj>" data is used for putting text beside other picture icons , and so if using only text based labels, we can substitute it with,
lv_scr_act() (or) NULL

'''<new_x>, <new_y>''' are the cartesian coordinates, '''<location parameter>''' is replaced by '''LV_ALIGN_<preset>''',
there will be a picture showing the presets below, and '''<text/obj>''' is your text label...

here, LV_ALIGN_<preset> sets the cartesian origin...

Label positioning based on alignment is both a simple and complicated thing to understand, so here I have given something you can refer to while modifying the position of the various labels and objects...

you can also refer here for LVGL's documentation of coordinate system https://docs.lvgl.io/v6/en/html/object-types/obj.html#coordinates

It is however recommended that you use the first method to set the location
lv_obj_set_pos(<obj>, <new_x>, <new_y>)
as it is simple and easier for beginners

Here is a small example.

Take the Label that tells the date,
In the source file (clock.cpp) it is this line,
lv_obj_align(label_date, lv_scr_act(), LV_ALIGN_IN_LEFT_MID, 0, 60);
by increasing the Value of the Y coordinate (60) to a higher value, we can bring the position of the Date downwards a bit away from the Time, and toward the Heartbeat count in the bottom row
here I will increase it to 80, so it becomes..
lv_obj_align(label_date, lv_scr_act(), LV_ALIGN_IN_LEFT_MID, 0, 80);

and now we have made some space up top..

now let's try something a bit complex,

Take the position argument for the label that tells you time...
here, in the source file (clock.cpp),
lv_obj_align(label_time, lv_scr_act(), LV_ALIGN_IN_LEFT_MID, 0, 0);

this line determines the position of the Label telling time, as seen in the image...

we modifying this, by changing the origin <preset> parameter (here it is LV_ALIGN_IN_LEFT_MID) to LV_ALIGN_IN_TOP_LEFT

you can alternatively swap the whole line to,
lv_obj_set_pos(label_time, 0, 0);

this makes the Time label/obj. to go to the top left corner...

but I will do something a little extra,
I will modify the label that store the data and Time format,
i.e this line,
sprintf(timeStr, "%c%c:%c%c", hoursChar[0],hoursChar[1],minutesChar[0], minutesChar[1]);

by removing the ":" colon in between the numbers, and replacing it with a Newline symbol "\n"
I change it to become,
sprintf(timeStr, "%c%c\n%c%c", hoursChar[0],hoursChar[1],minutesChar[0], minutesChar[1]);

this gives it a nice wrapped text format in the top corner, and gives us some space to play with in the side, for things like Pictures and icons, which we will do next..

If you have been able to do these things, you now have completed the 2nd part of the tutorial, and now know how to change and modify the position of labels..

==Using icons==
The LVGL library allows for the use of widgets known as "Images", In short it allows you to use small Icons like pictures with a small dedicated function,
However when this was attempted the first time we stumbled on some problems as LVGL v6 (used on the pinetime) is not much documented as the latest release (v7 as of August 2020)
but also the existing code was only documented for C not C++, after some painful attempts we were able to translate it into C++,

To bring images into Clock.cpp
you will need to do the following,

1. Have a small image that cannot exceed a maximum size of 240px x 240px (pinetime max resolution)

2. Use this Image converter (Thanks to LVGL) https://lvgl.io/tools/imageconverter
to convert your image to a C array and having the Color format as "True color" and the output format as "C array"
make sure to use something simple as the name we will be using "bitmap" as the name, but will also be referred as <name> for simplicity

Note: for example we shall use <name> = bitmap, but any simple word can be used, as long as it does not cause problems with system variables

===Image size considerations===
since the image will be using the flash directly, we need to be considerate about flash memory usage.

<picture_X> x <picture_Y> x 2
gives you the number of KB the image used in storage...

where, <picture_X> <picture_Y> are the dimensions of the image horizontally and vertically

for example,
if <picture_X>=80px <picture_Y>=64px
then,
total storage used = 80 x 60 x 2 = 10.24KB

please use the flash storage with consideration, when using other apps as well, excess usage of storage
might mean the Firmware will not compile... the limit to storage to about 400Kb for the user, the
firmware size must not exceed that...

==Preparing the image for inclusion as an icon==

Once you have your obtained your C array from the LVGL converter, you can take a look inside it to see all the different formats of your image,
try using something like Notepad++ or any of your favorite text editors to peek inside of it,

there will be 4 sets of Arrays inside it that look like,

#if LV_COLOR_DEPTH == 1 || LV_COLOR_DEPTH == 8
/*Pixel format: Red: 3 bit, Green: 3 bit, Blue: 2 bit*/
0x00, 0x00, 0x00,...
...0x00, 0x00, 0x00,
#endif

#if LV_COLOR_DEPTH == 16 && LV_COLOR_16_SWAP == 0
/*Pixel format: Red: 5 bit, Green: 6 bit, Blue: 5 bit*/
0x00, 0x00, 0x00,...
...0x00, 0x00, 0x00,
#endif

#if LV_COLOR_DEPTH == 16 && LV_COLOR_16_SWAP != 0
/*Pixel format: Red: 5 bit, Green: 6 bit, Blue: 5 bit BUT the 2 bytes are swapped*/
0x00, 0x00, 0x00,...
...0x00, 0x00, 0x00,
#endif

#if LV_COLOR_DEPTH == 32
/*Pixel format: Fix 0xFF: 8 bit, Red: 8 bit, Green: 8 bit, Blue: 8 bit*/
0x00, 0x00, 0x00,...
...0x00, 0x00, 0xff,
#endif
};

And another small bit of info we will need for later that looks like,

const lv_img_dsc_t bitmap = {
.header.always_zero = 0,
.header.w = 40,
.header.h = 40,
.data_size = 1600 * LV_COLOR_SIZE / 8,
.header.cf = LV_IMG_CF_TRUE_COLOR,
.data = bitmap_map,
};

NOTE: There are some header files at the top, which we can ignore...
===RGB565 image format===

The Pinetime uses a display that uses a 16 bit color space, also known as RGB565.

These 16 bit are assigned to RGB as 5 bits each for Red and Blue and 6 bits for Green, so 5+6+5=16 bits are required, so each pixel's color occupies 2 bytes of data,
and since 216 is equal to 65,536 it allows us to view 65,536 or 65k colors

The way it packs these bits is by converting the bits into 2x 4+4 bit hex-code, so for example,

if the color of a pixel in Binary is '''10110100 01011111''' (this color is approximately Lavender purple)

It is split as '''1011''' & '''0100''' for the first byte and '''0101''' & '''1111''' for the second byte
and so, converting the binary into Hex-code,

the two parts are '''0xB4''' and '''0xF5'''

These two parts in conjunction are used for determining the color of one pixel...

also from the binary, it is observed that,

The bits '''10110''' is used for Red, '''100010''' is used for green, and '''11111''' is used for blue.

===Flipping the bytes===
The LVGL library has a feature that allows you to flip the two bytes of the pixel, so if the two parts were, ...0xB4,0xF5,... ,it will change it to become, ...0xF5,0xB4,...

The reason for this is to allow the use of 8-bit SPI interfaces, but we do not require it, and if set with wrong parameter we could get problems with the color...

To make sure you are ready for the next step, make sure that inside your lvgl configuration file (located at '''src/libs/lv_conf.h''')

this parameter,
'''#define LV_COLOR_16_SWAP 1'''
is set to "1" as seen...

NOTE: if you haven't modified it or tampered with it with your Github fork, you shouldn't have a problem
as it is correct by default, and you can skip these steps

===Creating an Object from the Array===
To include the Icon, first Identify the Array you need to copy to the source (clock.cpp)

The one we require from it is the data below the tag that looks like,
#if LV_COLOR_DEPTH == 16 && LV_COLOR_16_SWAP == 0
/*Pixel format: Red: 5 bit, Green: 6 bit, Blue: 5 bit BUT the 2 bytes are swapped*/
0x00, 0x00, 0x00,...
...0x00, 0x00, 0x00,
#endif

from this copy the Data from the array alone...
I.e this part,
0x00, 0x00, 0x00,...
...0x00, 0x00, 0x00

(Make sure to not include the comma at the end or the #endif as the entire part is going to substitute a new array)

In clock.cpp, just below the header files and the Task creation part (I.e event_handler...),
create a name for the label with,
static lv_img_dsc_t <name>; // remember to replace <name> with the actual name you gave to your image while converting !

then below it create a array to hold the data with,
const uint8_t bitmap_map[] = {<data>}; // paste the array you copied from the conversion file we specified above...

Then inside the Clock::Clock(DisplayApp* app,...){... region,
You need to place a particular set of lines which LVGL uses to define the object declare the array as an Icon/Image, You can place this set of lines above label_time...

<name>.header.always_zero = 0; //Initialization
<name>.header.w = <picture_X>; // Setting the Width (or) Horizontal length of the image (number of px)
<name>.header.h = <picture_Y>; // Setting the Height (or) vertical length of the image (number of px)
<name>.data_size = <Hr_length> * <Vr_length> * LV_COLOR_SIZE / 8; //Allocation of memory for the image
<name>.header.cf = LV_IMG_CF_TRUE_COLOR; // Sets the color scheme for the image
<name>.data = <name>_map; // Maps the Image data to the Array
lv_obj_t *img_src = lv_img_create(lv_scr_act(), NULL); // Create an image object
lv_img_set_src(img_src, &<name>); // Set the created file as image (<name>)

again, make sure to replace <name> with the name you gave it during conversion!

Now that we have bought in the image data, we need to set the position, you can place this just below the lines we wrote for bringing in the image, It can be done with either,
lv_obj_set_pos(img_src, <x_pos, <y_pos>); // <x_pos>, <y_pos> are the coordinates of the cartesian plane
or,
lv_obj_align(img_src, lv_scr_act(), LV_ALIGN_<parameter>, <x_pos, <y_pos>);

If done correctly, you will now have a beautiful little Icon/Image in your Watch face,
Make sure that your Watch face can accommodate the Image by pushing the other labels farther away creating space for it...

We have provided a small template you can use for adding even a large image comfortably

If you have succeeded with this, you have completed part 3 of the tutorial.

=Using git to work on the firmware=
===Cloning the repository===
===Changing the code to add the image===
===Compiling the firmware===
==Testing the firmware==
===Installing the new firmware===

A holistic guide on how to install different firmware using various hardware programmers is available here: [[Reprogramming the PineTime]]. There's also the possibility of using OTA updating. ''//TODO: add that to the article!''

===Activating the firmware===
===How to troubleshoot===
==Conclusions==
==Next steps==
==More in-depth documentation==
==Thanks for the help==

File:LVGL coord system.png

2020-09-23T14:54:37Z

Electr0lyte: This displays the coordiniate system used by the lv_set_pos(...) function in LVGL

== Summary ==
This displays the coordiniate system used by the lv_set_pos(...) function in LVGL
== Licensing ==
{{GPL|GPL}}

PineTime Custom Watchface Tutorial

2020-08-18T08:46:43Z

Electr0lyte: /* Image size considerations */

=PineTime Custom Watchface Tutorial=

This is a tutorial to help new users create custom watchfaces based on the InfiniTime Firmware for Pinetime made by user JF002, thanks to him for its development...

We will explain some of the things we went through while creating some custom Watchfaces, so consider this as a log of experiments of sorts..

So stay tuned to it as it will be dynamically updated...

==What you need to start==
The entire building process will be done by GitHub, so all you need is a device which can give you a Github Web Client, a PC or tablet to give you enough screen space to review your code and a steady internet connection.

Since the compiling and file management is done by Github online, you have nothing else to worry about other than working with the files that display the watch face.

So with those things settled, let's start with the basics of a watchface.

Please remember that this is a wiki, so you can make an account and help us improve this page.

Please make sure not to unilaterally remove info though, but offer an alternative. If it is indeed a better way, in time your alternative will grow into the main text, and the latter info will be pruned.

==Overview==
The Firmware (also called InfiniTime) we will be working with is made with a programming language named '''C++''':[https://en.wikipedia.org/wiki/C%2B%2B]

Basic knowledge of C/C++ is required to to understand the advanced watch faces as that requires more complex code, but you can still do a some cool things without much knowledge of C++ programming, just some small edits to existing programs.

InfiniTime uses the '''LVGL''':[https://lvgl.io] graphics library to provide users with a simple and clean UI without overpowering the Nordic '''nRF52832''':[http://files.pine64.org/doc/datasheet/pinetime/nRF52832%20product%20brief.pdf] microcontroller which is the brain of the watch.

To get the watchface to work there are these basic steps. We will go over each step separately, so don't be daunted, all will become clear soon.

For now we will, modify the the existing watchface, change the positioning of the text labels, add an icon to an existing watchface, and later on we will do a full watchface.

The main file we need to focus on is the '''clock.cpp''' file, it is what contains most of the data attributed to what we see on the watchface, including The time/day characters, the battery and bluetooth icons, and also pedometer count...

so everything we will be doing in the basic modifications is purely messing with this single file.

==Labels==
===What are labels?===
Labels are considered as "elemental" parts that make up a screen's Text-based UI by the LVGL library...
Each label is also considered as an "object" or "obj" and can be manipulated, by changing the data attributed with the "obj", for example, position, internal data like the strings/text etc.
when can change what the label shows and where it shows it...

===Modifying label data===
let's observe something small like the word "BPM" near the bottom of the watch face...
[[file:PineTimeCustom-1.png|right|200px]]

If we take a look at the source file of the watchface, (a.k.a the clock.cpp file)
we can observe that these particular lines are what attributes to the word "BPM being displayed...
heartbeatBpm = lv_label_create(lv_scr_act(), NULL);
lv_label_set_text(heartbeatBpm, "BPM");

we can modify the text inside the quotes and replace the word 'BPM' between those quotes to something like 'LOVE'
and the result after compiling the firmware again with the changes and flashing it to the watch would be that the text changes on the watch face and displays 'LOVE' inplace of 'BPM'...

If this happened correctly, then you have successfully made a custom new watchface! Now we can do something a bit more complex...

Now take for in instance the days of the week that we have on the bottom line with the date...

they are stored a "C array" which is basically multiple words separated by commas..
the date is in a format of '''<day of the week> <day> <Month> <year>'''

which in the source file is expressed as,
sprintf(dateStr, "%s %d %s %d", DayOfWeekToString(dayOfWeek), day, MonthToString(month), year);
lv_label_set_text(label_date, dateStr);

here,
%s %d %s %d
stores the print format of the variables, and

DayOfWeekToString(dayOfWeek), day, MonthToString(month), year
are the variables themselves...

Now,
if the date was a saturday 11/7/2020, you can observe that the date looks like
SATURDAY 11 JUL 2020
as seen in the above image (the one where we changed BPM to LOVE)

by modifying the format of the variables, we can change how those words are arranged, and add some extra characters if we like...
(there is a catch to the list of characters you can use however, but it will be discussed later...)

For example,

We modifying the format by adding a comma... "," in between the second "%s" and "%d" like this,
"%s %d %s, %d"
and changing that in the line...
sprintf(dateStr, "%s %d %s, %d", DayOfWeekToString(dayOfWeek), day, MonthToString(month), year);

we can make the date become...
SATURDAY 11 JUL, 2020

which means we now were able to modify how the text got display to make it a bit more nice...

but if you haven't noticed, the line containing the date is already full, meaning we will get some problems while displaying the date and causing it to wrap around,
making a single character go to the next line and look more like,

SATURDAY 11 JUL, 202
0

so why don't we shorten the characters present in the date from being "SATURDAY" to simply just "sat." (It will have the small period at the end, and is only 3 characters long)
I will also convert the months of the year from Capital to small letters...

for that look into the part where the days of the week of are stored as text,
and also while looking at it, we can solve another question, why was their two variables in the date format that looked like, DayOfWeekToString(dayOfWeek), and MonthToString(month) ?

It is because the system gives the date/ time as numbers (Monday-1, Tuesday-2 Wednesday-3 for the days, and 1-January, 2-February, 3-March ),
and so a function along with a C array is used to assign these numbers to Days/Months in text form as it is easier to read...

this is the Array containing the day of the week, (as text)
char const *Clock::DaysString[] = {
"",
"MONDAY",
"TUESDAY",
"WEDNESDAY",
"THURSDAY",
"FRIDAY",
"SATURDAY",
"SUNDAY"
};

and this Array stores the months of the year, (as text)
char const *Clock::MonthsString[] = {
"",
"JAN",
"FEB",
"MAR",
"APR",
"MAY",
"JUN",
"JUL",
"AUG",
"SEP",
"OCT",
"NOV",
"DEC"
};

here we can see that the days are stored in a full format as "SUNDAY", "MONDAY", "TUESDAY" etc.
we can change all of them to a shorter format like "sun.", "mon.", "tue.", to make it short and nice...
while doing so, we can even make the months use small letters as said before..

so the source file (clock.cpp) becomes,

(for the days of the week)
char const *Clock::DaysString[] = {
"",
"mon.",
"tue.",
"wed.",
"thu.",
"fri.",
"sat.",
"sun."
};

and

(for the months of the year)
char const *Clock::MonthsString[] = {
"",
"jan",
"feb",
"mar",
"apr",
"may",
"jun",
"jul",
"aug",
"sep",
"oct",
"nov",
"dec"
};

which means now our original date, saturday 11/7/2020 will become...
sat. 11 jul, 2020

you now know how to change the data present in a label object, and the format of it..,

Here is a fun idea you can try: you can even replace the days with whatever thing that tells you (or) reminds you the day of the week
(like the food served in the cafe, Monday/taco, Tuesday/burger, Wednesday/pasta etc.)

NOTE: when making the custom array, don't forget to leave a empty "" as the first element of the array,
This is because the date is given by the system in a natural numbers format (1,2,3...) rather than a zero-starting format (0,1,2,3...), which the C array uses to index...
so the C array indexes the days as ""-0, "Monday"-1, "Tuesday"-2 etc. and the months as ""-0, "January"-1, "February"-2 etc.)

===Label positioning===

The locational placement in LVGL is done on a cartesian plane,
where each object can have dynamic origin placement, and the Y-axis is inverted...
So going down is done with a positive Y-axis value and not negative as the it is by de-facto...

The position of the various objects in clock.cpp are set by the line,
lv_obj_set_pos(<obj>, <new_x>, <new_y>)

and the top left corner is the Cartesian origin, aka coordinates (0,0)

we use another function, that is more advanced that gives the positional alignment based on preset locations...
lv_obj_align(<text/obj>, <image/obj>, <location_parameter>, <new_x>, <new_y>);

the "<image/obj>" data is used for putting text beside other picture icons , and so if using only text based labels, we can substitute it with,
lv_scr_act() (or) NULL

'''<new_x>, <new_y>''' are the cartesian coordinates, '''<location parameter>''' is replaced by '''LV_ALIGN_<preset>''',
there will be a picture showing the presets below, and '''<text/obj>''' is your text label...

here, LV_ALIGN_<preset> sets the cartesian origin...

Label positioning based on alignment is both a simple and complicated thing to understand, so here I have given something you can refer to while modifying the position of the various labels and objects...

you can also refer here for LVGL's documentation of coordinate system https://docs.lvgl.io/v6/en/html/object-types/obj.html#coordinates

It is however recommended that you use the first method to set the location
lv_obj_set_pos(<obj>, <new_x>, <new_y>)
as it is simple and easier for beginners

Here is a small example.

Take the Label that tells the date,
In the source file (clock.cpp) it is this line,
lv_obj_align(label_date, lv_scr_act(), LV_ALIGN_IN_LEFT_MID, 0, 60);
by increasing the Value of the Y coordinate (60) to a higher value, we can bring the position of the Date downwards a bit away from the Time, and toward the Heartbeat count in the bottom row
here I will increase it to 80, so it becomes..
lv_obj_align(label_date, lv_scr_act(), LV_ALIGN_IN_LEFT_MID, 0, 80);

and now we have made some space up top..

now let's try something a bit complex,

Take the position argument for the label that tells you time...
here, in the source file (clock.cpp),
lv_obj_align(label_time, lv_scr_act(), LV_ALIGN_IN_LEFT_MID, 0, 0);

this line determines the position of the Label telling time, as seen in the image...

we modifying this, by changing the origin <preset> parameter (here it is LV_ALIGN_IN_LEFT_MID) to LV_ALIGN_IN_TOP_LEFT

you can alternatively swap the whole line to,
lv_obj_set_pos(label_time, 0, 0);

this makes the Time label/obj. to go to the top left corner...

but I will do something a little extra,
I will modify the label that store the data and Time format,
i.e this line,
sprintf(timeStr, "%c%c:%c%c", hoursChar[0],hoursChar[1],minutesChar[0], minutesChar[1]);

by removing the ":" colon in between the numbers, and replacing it with a Newline symbol "\n"
I change it to become,
sprintf(timeStr, "%c%c\n%c%c", hoursChar[0],hoursChar[1],minutesChar[0], minutesChar[1]);

this gives it a nice wrapped text format in the top corner, and gives us some space to play with in the side, for things like Pictures and icons, which we will do next..

If you have been able to do these things, you now have completed the 2nd part of the tutorial, and now know how to change and modify the position of labels..

==Using icons==
The LVGL library allows for the use of widgets known as "Images", In short it allows you to use small Icons like pictures with a small dedicated function,
However when this was attempted the first time we stumbled on some problems as LVGL v6 (used on the pinetime) is not much documented as the latest release (v7 as of August 2020)
but also the existing code was only documented for C not C++, after some painful attempts we were able to translate it into C++,

To bring images into Clock.cpp
you will need to do the following,

1. Have a small image that cannot exceed a maximum size of 240px x 240px (pinetime max resolution)

2. Use this Image converter (Thanks to LVGL) https://lvgl.io/tools/imageconverter
to convert your image to a C array and having the Color format as "True color" and the output format as "C array"
make sure to use something simple as the name we will be using "bitmap" as the name, but will also be referred as <name> for simplicity

Note: for example we shall use <name> = bitmap, but any simple word can be used, as long as it does not cause problems with system variables

===Image size considerations===
since the image will be using the flash directly, we need to be considerate about flash memory usage.

<picture_X> x <picture_Y> x 2
gives you the number of KB the image used in storage...

where, <picture_X> <picture_Y> are the dimensions of the image horizontally and vertically

for example,
if <picture_X>=80px <picture_Y>=64px
then,
total storage used = 80 x 60 x 2 = 10.24KB

please use the flash storage with consideration, when using other apps as well, excess usage of storage
might mean the Firmware will not compile... the limit to storage to about 400Kb for the user, the
firmware size must not exceed that...

==Preparing the image for inclusion as an icon==

Once you have your obtained your C array from the LVGL converter, you can take a look inside it to see all the different formats of your image,
try using something like Notepad++ or any of your favorite text editors to peek inside of it,

there will be 4 sets of Arrays inside it that look like,

#if LV_COLOR_DEPTH == 1 || LV_COLOR_DEPTH == 8
/*Pixel format: Red: 3 bit, Green: 3 bit, Blue: 2 bit*/
0x00, 0x00, 0x00,...
...0x00, 0x00, 0x00,
#endif

#if LV_COLOR_DEPTH == 16 && LV_COLOR_16_SWAP == 0
/*Pixel format: Red: 5 bit, Green: 6 bit, Blue: 5 bit*/
0x00, 0x00, 0x00,...
...0x00, 0x00, 0x00,
#endif

#if LV_COLOR_DEPTH == 16 && LV_COLOR_16_SWAP != 0
/*Pixel format: Red: 5 bit, Green: 6 bit, Blue: 5 bit BUT the 2 bytes are swapped*/
0x00, 0x00, 0x00,...
...0x00, 0x00, 0x00,
#endif

#if LV_COLOR_DEPTH == 32
/*Pixel format: Fix 0xFF: 8 bit, Red: 8 bit, Green: 8 bit, Blue: 8 bit*/
0x00, 0x00, 0x00,...
...0x00, 0x00, 0xff,
#endif
};

And another small bit of info we will need for later that looks like,

const lv_img_dsc_t bitmap = {
.header.always_zero = 0,
.header.w = 40,
.header.h = 40,
.data_size = 1600 * LV_COLOR_SIZE / 8,
.header.cf = LV_IMG_CF_TRUE_COLOR,
.data = bitmap_map,
};

NOTE: There are some header files at the top, which we can ignore...
===RGB565 image format===

The Pinetime uses a display that uses a 16 bit color space, also known as RGB565.

These 16 bit are assigned to RGB as 5 bits each for Red and Blue and 6 bits for Green, so 5+6+5=16 bits are required, so each pixel's color occupies 2 bytes of data,
and since 216 is equal to 65,536 it allows us to view 65,536 or 65k colors

The way it packs these bits is by converting the bits into 2x 4+4 bit hex-code, so for example,

if the color of a pixel in Binary is '''10110100 01011111''' (this color is approximately Lavender purple)

It is split as '''1011''' & '''0100''' for the first byte and '''0101''' & '''1111''' for the second byte
and so, converting the binary into Hex-code,

the two parts are '''0xB4''' and '''0xF5'''

These two parts in conjunction are used for determining the color of one pixel...

also from the binary, it is observed that,

The bits '''10110''' is used for Red, '''100010''' is used for green, and '''11111''' is used for blue.

===Flipping the bytes===
The LVGL library has a feature that allows you to flip the two bytes of the pixel, so if the two parts were, ...0xB4,0xF5,... ,it will change it to become, ...0xF5,0xB4,...

The reason for this is to allow the use of 8-bit SPI interfaces, but we do not require it, and if set with wrong parameter we could get problems with the color...

To make sure you are ready for the next step, make sure that inside your lvgl configuration file (located at '''src/libs/lv_conf.h''')

this parameter,
'''#define LV_COLOR_16_SWAP 1'''
is set to "1" as seen...

NOTE: if you haven't modified it or tampered with it with your Github fork, you shouldn't have a problem
as it is correct by default, and you can skip these steps

===Creating an Object from the Array===
To include the Icon, first Identify the Array you need to copy to the source (clock.cpp)

The one we require from it is the data below the tag that looks like,
#if LV_COLOR_DEPTH == 16 && LV_COLOR_16_SWAP == 0
/*Pixel format: Red: 5 bit, Green: 6 bit, Blue: 5 bit BUT the 2 bytes are swapped*/
0x00, 0x00, 0x00,...
...0x00, 0x00, 0x00,
#endif

from this copy the Data from the array alone...
I.e this part,
0x00, 0x00, 0x00,...
...0x00, 0x00, 0x00

(Make sure to not include the comma at the end or the #endif as the entire part is going to substitute a new array)

In clock.cpp, just below the header files and the Task creation part (I.e event_handler...),
create a name for the label with,
static lv_img_dsc_t <name>; // remember to replace <name> with the actual name you gave to your image while converting !

then below it create a array to hold the data with,
const uint8_t bitmap_map[] = {<data>}; // paste the array you copied from the conversion file we specified above...

Then inside the Clock::Clock(DisplayApp* app,...){... region,
You need to place a particular set of lines which LVGL uses to define the object declare the array as an Icon/Image, You can place this set of lines above label_time...

<name>.header.always_zero = 0; //Initialization
<name>.header.w = <picture_X>; // Setting the Width (or) Horizontal length of the image (number of px)
<name>.header.h = <picture_Y>; // Setting the Height (or) vertical length of the image (number of px)
<name>.data_size = <Hr_length> * <Vr_length> * LV_COLOR_SIZE / 8; //Allocation of memory for the image
<name>.header.cf = LV_IMG_CF_TRUE_COLOR; // Sets the color scheme for the image
<name>.data = <name>_map; // Maps the Image data to the Array
lv_obj_t *img_src = lv_img_create(lv_scr_act(), NULL); // Create an image object
lv_img_set_src(img_src, &<name>); // Set the created file as image (<name>)

again, make sure to replace <name> with the name you gave it during conversion!

Now that we have bought in the image data, we need to set the position, you can place this just below the lines we wrote for bringing in the image, It can be done with either,
lv_obj_set_pos(img_src, <x_pos, <y_pos>); // <x_pos>, <y_pos> are the coordinates of the cartesian plane
or,
lv_obj_align(img_src, lv_scr_act(), LV_ALIGN_<parameter>, <x_pos, <y_pos>);

If done correctly, you will now have a beautiful little Icon/Image in your Watch face,
Make sure that your Watch face can accommodate the Image by pushing the other labels farther away creating space for it...

We have provided a small template you can use for adding even a large image comfortably

If you have succeeded with this, you have completed part 3 of the tutorial.

=Using git to work on the firmware=
===Cloning the repository===
===Changing the code to add the image===
===Compiling the firmware===
==Testing the firmware==
===Installing the new firmware===

A holistic guide on how to install different firmware using various hardware programmers is available here: [[Reprogramming the PineTime]]. There's also the possibility of using OTA updating. ''//TODO: add that to the article!''

===Activating the firmware===
===How to troubleshoot===
==Conclusions==
==Next steps==
==More in-depth documentation==
==Thanks for the help==

PineTime Custom Watchface Tutorial

2020-08-18T03:57:24Z

Electr0lyte: /* Creating an Object from the Array */

=PineTime Custom Watchface Tutorial=

This is a tutorial to help new users create custom watchfaces based on the InfiniTime Firmware for Pinetime made by user JF002, thanks to him for its development...

We will explain some of the things we went through while creating some custom Watchfaces, so consider this as a log of experiments of sorts..

So stay tuned to it as it will be dynamically updated...

==What you need to start==
The entire building process will be done by GitHub, so all you need is a device which can give you a Github Web Client, a PC or tablet to give you enough screen space to review your code and a steady internet connection.

Since the compiling and file management is done by Github online, you have nothing else to worry about other than working with the files that display the watch face.

So with those things settled, let's start with the basics of a watchface.

Please remember that this is a wiki, so you can make an account and help us improve this page.

Please make sure not to unilaterally remove info though, but offer an alternative. If it is indeed a better way, in time your alternative will grow into the main text, and the latter info will be pruned.

==Overview==
The Firmware (also called InfiniTime) we will be working with is made with a programming language named '''C++''':[https://en.wikipedia.org/wiki/C%2B%2B]

Basic knowledge of C/C++ is required to to understand the advanced watch faces as that requires more complex code, but you can still do a some cool things without much knowledge of C++ programming, just some small edits to existing programs.

InfiniTime uses the '''LVGL''':[https://lvgl.io] graphics library to provide users with a simple and clean UI without overpowering the Nordic '''nRF52832''':[http://files.pine64.org/doc/datasheet/pinetime/nRF52832%20product%20brief.pdf] microcontroller which is the brain of the watch.

To get the watchface to work there are these basic steps. We will go over each step separately, so don't be daunted, all will become clear soon.

For now we will, modify the the existing watchface, change the positioning of the text labels, add an icon to an existing watchface, and later on we will do a full watchface.

The main file we need to focus on is the '''clock.cpp''' file, it is what contains most of the data attributed to what we see on the watchface, including The time/day characters, the battery and bluetooth icons, and also pedometer count...

so everything we will be doing in the basic modifications is purely messing with this single file.

==Labels==
===What are labels?===
Labels are considered as "elemental" parts that make up a screen's Text-based UI by the LVGL library...
Each label is also considered as an "object" or "obj" and can be manipulated, by changing the data attributed with the "obj", for example, position, internal data like the strings/text etc.
when can change what the label shows and where it shows it...

===Modifying label data===
let's observe something small like the word "BPM" near the bottom of the watch face...
[[file:PineTimeCustom-1.png|right|200px]]

If we take a look at the source file of the watchface, (a.k.a the clock.cpp file)
we can observe that these particular lines are what attributes to the word "BPM being displayed...
heartbeatBpm = lv_label_create(lv_scr_act(), NULL);
lv_label_set_text(heartbeatBpm, "BPM");

we can modify the text inside the quotes and replace the word 'BPM' between those quotes to something like 'LOVE'
and the result after compiling the firmware again with the changes and flashing it to the watch would be that the text changes on the watch face and displays 'LOVE' inplace of 'BPM'...

If this happened correctly, then you have successfully made a custom new watchface! Now we can do something a bit more complex...

Now take for in instance the days of the week that we have on the bottom line with the date...

they are stored a "C array" which is basically multiple words separated by commas..
the date is in a format of '''<day of the week> <day> <Month> <year>'''

which in the source file is expressed as,
sprintf(dateStr, "%s %d %s %d", DayOfWeekToString(dayOfWeek), day, MonthToString(month), year);
lv_label_set_text(label_date, dateStr);

here,
%s %d %s %d
stores the print format of the variables, and

DayOfWeekToString(dayOfWeek), day, MonthToString(month), year
are the variables themselves...

Now,
if the date was a saturday 11/7/2020, you can observe that the date looks like
SATURDAY 11 JUL 2020
as seen in the above image (the one where we changed BPM to LOVE)

by modifying the format of the variables, we can change how those words are arranged, and add some extra characters if we like...
(there is a catch to the list of characters you can use however, but it will be discussed later...)

For example,

We modifying the format by adding a comma... "," in between the second "%s" and "%d" like this,
"%s %d %s, %d"
and changing that in the line...
sprintf(dateStr, "%s %d %s, %d", DayOfWeekToString(dayOfWeek), day, MonthToString(month), year);

we can make the date become...
SATURDAY 11 JUL, 2020

which means we now were able to modify how the text got display to make it a bit more nice...

but if you haven't noticed, the line containing the date is already full, meaning we will get some problems while displaying the date and causing it to wrap around,
making a single character go to the next line and look more like,

SATURDAY 11 JUL, 202
0

so why don't we shorten the characters present in the date from being "SATURDAY" to simply just "sat." (It will have the small period at the end, and is only 3 characters long)
I will also convert the months of the year from Capital to small letters...

for that look into the part where the days of the week of are stored as text,
and also while looking at it, we can solve another question, why was their two variables in the date format that looked like, DayOfWeekToString(dayOfWeek), and MonthToString(month) ?

It is because the system gives the date/ time as numbers (Monday-1, Tuesday-2 Wednesday-3 for the days, and 1-January, 2-February, 3-March ),
and so a function along with a C array is used to assign these numbers to Days/Months in text form as it is easier to read...

this is the Array containing the day of the week, (as text)
char const *Clock::DaysString[] = {
"",
"MONDAY",
"TUESDAY",
"WEDNESDAY",
"THURSDAY",
"FRIDAY",
"SATURDAY",
"SUNDAY"
};

and this Array stores the months of the year, (as text)
char const *Clock::MonthsString[] = {
"",
"JAN",
"FEB",
"MAR",
"APR",
"MAY",
"JUN",
"JUL",
"AUG",
"SEP",
"OCT",
"NOV",
"DEC"
};

here we can see that the days are stored in a full format as "SUNDAY", "MONDAY", "TUESDAY" etc.
we can change all of them to a shorter format like "sun.", "mon.", "tue.", to make it short and nice...
while doing so, we can even make the months use small letters as said before..

so the source file (clock.cpp) becomes,

(for the days of the week)
char const *Clock::DaysString[] = {
"",
"mon.",
"tue.",
"wed.",
"thu.",
"fri.",
"sat.",
"sun."
};

and

(for the months of the year)
char const *Clock::MonthsString[] = {
"",
"jan",
"feb",
"mar",
"apr",
"may",
"jun",
"jul",
"aug",
"sep",
"oct",
"nov",
"dec"
};

which means now our original date, saturday 11/7/2020 will become...
sat. 11 jul, 2020

you now know how to change the data present in a label object, and the format of it..,

Here is a fun idea you can try: you can even replace the days with whatever thing that tells you (or) reminds you the day of the week
(like the food served in the cafe, Monday/taco, Tuesday/burger, Wednesday/pasta etc.)

NOTE: when making the custom array, don't forget to leave a empty "" as the first element of the array,
This is because the date is given by the system in a natural numbers format (1,2,3...) rather than a zero-starting format (0,1,2,3...), which the C array uses to index...
so the C array indexes the days as ""-0, "Monday"-1, "Tuesday"-2 etc. and the months as ""-0, "January"-1, "February"-2 etc.)

===Label positioning===

The locational placement in LVGL is done on a cartesian plane,
where each object can have dynamic origin placement, and the Y-axis is inverted...
So going down is done with a positive Y-axis value and not negative as the it is by de-facto...

The position of the various objects in clock.cpp are set by the line,
lv_obj_set_pos(<obj>, <new_x>, <new_y>)

and the top left corner is the Cartesian origin, aka coordinates (0,0)

we use another function, that is more advanced that gives the positional alignment based on preset locations...
lv_obj_align(<text/obj>, <image/obj>, <location_parameter>, <new_x>, <new_y>);

the "<image/obj>" data is used for putting text beside other picture icons , and so if using only text based labels, we can substitute it with,
lv_scr_act() (or) NULL

'''<new_x>, <new_y>''' are the cartesian coordinates, '''<location parameter>''' is replaced by '''LV_ALIGN_<preset>''',
there will be a picture showing the presets below, and '''<text/obj>''' is your text label...

here, LV_ALIGN_<preset> sets the cartesian origin...

Label positioning based on alignment is both a simple and complicated thing to understand, so here I have given something you can refer to while modifying the position of the various labels and objects...

you can also refer here for LVGL's documentation of coordinate system https://docs.lvgl.io/v6/en/html/object-types/obj.html#coordinates

It is however recommended that you use the first method to set the location
lv_obj_set_pos(<obj>, <new_x>, <new_y>)
as it is simple and easier for beginners

Here is a small example.

Take the Label that tells the date,
In the source file (clock.cpp) it is this line,
lv_obj_align(label_date, lv_scr_act(), LV_ALIGN_IN_LEFT_MID, 0, 60);
by increasing the Value of the Y coordinate (60) to a higher value, we can bring the position of the Date downwards a bit away from the Time, and toward the Heartbeat count in the bottom row
here I will increase it to 80, so it becomes..
lv_obj_align(label_date, lv_scr_act(), LV_ALIGN_IN_LEFT_MID, 0, 80);

and now we have made some space up top..

now let's try something a bit complex,

Take the position argument for the label that tells you time...
here, in the source file (clock.cpp),
lv_obj_align(label_time, lv_scr_act(), LV_ALIGN_IN_LEFT_MID, 0, 0);

this line determines the position of the Label telling time, as seen in the image...

we modifying this, by changing the origin <preset> parameter (here it is LV_ALIGN_IN_LEFT_MID) to LV_ALIGN_IN_TOP_LEFT

you can alternatively swap the whole line to,
lv_obj_set_pos(label_time, 0, 0);

this makes the Time label/obj. to go to the top left corner...

but I will do something a little extra,
I will modify the label that store the data and Time format,
i.e this line,
sprintf(timeStr, "%c%c:%c%c", hoursChar[0],hoursChar[1],minutesChar[0], minutesChar[1]);

by removing the ":" colon in between the numbers, and replacing it with a Newline symbol "\n"
I change it to become,
sprintf(timeStr, "%c%c\n%c%c", hoursChar[0],hoursChar[1],minutesChar[0], minutesChar[1]);

this gives it a nice wrapped text format in the top corner, and gives us some space to play with in the side, for things like Pictures and icons, which we will do next..

If you have been able to do these things, you now have completed the 2nd part of the tutorial, and now know how to change and modify the position of labels..

==Using icons==
The LVGL library allows for the use of widgets known as "Images", In short it allows you to use small Icons like pictures with a small dedicated function,
However when this was attempted the first time we stumbled on some problems as LVGL v6 (used on the pinetime) is not much documented as the latest release (v7 as of August 2020)
but also the existing code was only documented for C not C++, after some painful attempts we were able to translate it into C++,

To bring images into Clock.cpp
you will need to do the following,

1. Have a small image that cannot exceed a maximum size of 240px x 240px (pinetime max resolution)

2. Use this Image converter (Thanks to LVGL) https://lvgl.io/tools/imageconverter
to convert your image to a C array and having the Color format as "True color" and the output format as "C array"
make sure to use something simple as the name we will be using "bitmap" as the name, but will also be referred as <name> for simplicity

Note: for example we shall use <name> = bitmap, but any simple word can be used, as long as it does not cause problems with system variables

===Image size considerations===
since the image will be written from internal Flash to the RAM, we need to be considerate as to use less RAM as we are capped at 64KB maximum...
for testing we did not exceed more than 30% of the 64KB which is about 19.2KB...

You can calculate the RAM usage of your images with a simple formula..
<picture_X> x <picture_Y> x 2
give you the number of KB the image uses...
where, <picture_X> <picture_Y> are the dimensions of the image horizontally and vertically

for example,
if <picture_X>=80px <picture_Y>=64px
then,
total RAM used = 80 x 60 x 2 = 10.24KB

please use the RAM sparingly, too much and the RAM overflow could cause the MCU to crash... you have been warned !!!

==Preparing the image for inclusion as an icon==

Once you have your obtained your C array from the LVGL converter, you can take a look inside it to see all the different formats of your image,
try using something like Notepad++ or any of your favorite text editors to peek inside of it,

there will be 4 sets of Arrays inside it that look like,

#if LV_COLOR_DEPTH == 1 || LV_COLOR_DEPTH == 8
/*Pixel format: Red: 3 bit, Green: 3 bit, Blue: 2 bit*/
0x00, 0x00, 0x00,...
...0x00, 0x00, 0x00,
#endif

#if LV_COLOR_DEPTH == 16 && LV_COLOR_16_SWAP == 0
/*Pixel format: Red: 5 bit, Green: 6 bit, Blue: 5 bit*/
0x00, 0x00, 0x00,...
...0x00, 0x00, 0x00,
#endif

#if LV_COLOR_DEPTH == 16 && LV_COLOR_16_SWAP != 0
/*Pixel format: Red: 5 bit, Green: 6 bit, Blue: 5 bit BUT the 2 bytes are swapped*/
0x00, 0x00, 0x00,...
...0x00, 0x00, 0x00,
#endif

#if LV_COLOR_DEPTH == 32
/*Pixel format: Fix 0xFF: 8 bit, Red: 8 bit, Green: 8 bit, Blue: 8 bit*/
0x00, 0x00, 0x00,...
...0x00, 0x00, 0xff,
#endif
};

And another small bit of info we will need for later that looks like,

const lv_img_dsc_t bitmap = {
.header.always_zero = 0,
.header.w = 40,
.header.h = 40,
.data_size = 1600 * LV_COLOR_SIZE / 8,
.header.cf = LV_IMG_CF_TRUE_COLOR,
.data = bitmap_map,
};

NOTE: There are some header files at the top, which we can ignore...
===RGB565 image format===

The Pinetime uses a display that uses a 16 bit color space, also known as RGB565.

These 16 bit are assigned to RGB as 5 bits each for Red and Blue and 6 bits for Green, so 5+6+5=16 bits are required, so each pixel's color occupies 2 bytes of data,
and since 216 is equal to 65,536 it allows us to view 65,536 or 65k colors

The way it packs these bits is by converting the bits into 2x 4+4 bit hex-code, so for example,

if the color of a pixel in Binary is '''10110100 01011111''' (this color is approximately Lavender purple)

It is split as '''1011''' & '''0100''' for the first byte and '''0101''' & '''1111''' for the second byte
and so, converting the binary into Hex-code,

the two parts are '''0xB4''' and '''0xF5'''

These two parts in conjunction are used for determining the color of one pixel...

also from the binary, it is observed that,

The bits '''10110''' is used for Red, '''100010''' is used for green, and '''11111''' is used for blue.

===Flipping the bytes===
The LVGL library has a feature that allows you to flip the two bytes of the pixel, so if the two parts were, ...0xB4,0xF5,... ,it will change it to become, ...0xF5,0xB4,...

The reason for this is to allow the use of 8-bit SPI interfaces, but we do not require it, and if set with wrong parameter we could get problems with the color...

To make sure you are ready for the next step, make sure that inside your lvgl configuration file (located at '''src/libs/lv_conf.h''')

this parameter,
'''#define LV_COLOR_16_SWAP 1'''
is set to "1" as seen...

NOTE: if you haven't modified it or tampered with it with your Github fork, you shouldn't have a problem
as it is correct by default, and you can skip these steps

===Creating an Object from the Array===
To include the Icon, first Identify the Array you need to copy to the source (clock.cpp)

The one we require from it is the data below the tag that looks like,
#if LV_COLOR_DEPTH == 16 && LV_COLOR_16_SWAP == 0
/*Pixel format: Red: 5 bit, Green: 6 bit, Blue: 5 bit BUT the 2 bytes are swapped*/
0x00, 0x00, 0x00,...
...0x00, 0x00, 0x00,
#endif

from this copy the Data from the array alone...
I.e this part,
0x00, 0x00, 0x00,...
...0x00, 0x00, 0x00

(Make sure to not include the comma at the end or the #endif as the entire part is going to substitute a new array)

In clock.cpp, just below the header files and the Task creation part (I.e event_handler...),
create a name for the label with,
static lv_img_dsc_t <name>; // remember to replace <name> with the actual name you gave to your image while converting !

then below it create a array to hold the data with,
const uint8_t bitmap_map[] = {<data>}; // paste the array you copied from the conversion file we specified above...

Then inside the Clock::Clock(DisplayApp* app,...){... region,
You need to place a particular set of lines which LVGL uses to define the object declare the array as an Icon/Image, You can place this set of lines above label_time...

<name>.header.always_zero = 0; //Initialization
<name>.header.w = <picture_X>; // Setting the Width (or) Horizontal length of the image (number of px)
<name>.header.h = <picture_Y>; // Setting the Height (or) vertical length of the image (number of px)
<name>.data_size = <Hr_length> * <Vr_length> * LV_COLOR_SIZE / 8; //Allocation of memory for the image
<name>.header.cf = LV_IMG_CF_TRUE_COLOR; // Sets the color scheme for the image
<name>.data = <name>_map; // Maps the Image data to the Array
lv_obj_t *img_src = lv_img_create(lv_scr_act(), NULL); // Create an image object
lv_img_set_src(img_src, &<name>); // Set the created file as image (<name>)

again, make sure to replace <name> with the name you gave it during conversion!

Now that we have bought in the image data, we need to set the position, you can place this just below the lines we wrote for bringing in the image, It can be done with either,
lv_obj_set_pos(img_src, <x_pos, <y_pos>); // <x_pos>, <y_pos> are the coordinates of the cartesian plane
or,
lv_obj_align(img_src, lv_scr_act(), LV_ALIGN_<parameter>, <x_pos, <y_pos>);

If done correctly, you will now have a beautiful little Icon/Image in your Watch face,
Make sure that your Watch face can accommodate the Image by pushing the other labels farther away creating space for it...

We have provided a small template you can use for adding even a large image comfortably

If you have succeeded with this, you have completed part 3 of the tutorial.

=Using git to work on the firmware=
===Cloning the repository===
===Changing the code to add the image===
===Compiling the firmware===
==Testing the firmware==
===Installing the new firmware===

A holistic guide on how to install different firmware using various hardware programmers is available here: [[Reprogramming the PineTime]]. There's also the possibility of using OTA updating. ''//TODO: add that to the article!''

===Activating the firmware===
===How to troubleshoot===
==Conclusions==
==Next steps==
==More in-depth documentation==
==Thanks for the help==

PineTime Custom Watchface Tutorial

2020-08-18T03:57:05Z

Electr0lyte: /* Flipping the bytes */

=PineTime Custom Watchface Tutorial=

This is a tutorial to help new users create custom watchfaces based on the InfiniTime Firmware for Pinetime made by user JF002, thanks to him for its development...

We will explain some of the things we went through while creating some custom Watchfaces, so consider this as a log of experiments of sorts..

So stay tuned to it as it will be dynamically updated...

==What you need to start==
The entire building process will be done by GitHub, so all you need is a device which can give you a Github Web Client, a PC or tablet to give you enough screen space to review your code and a steady internet connection.

Since the compiling and file management is done by Github online, you have nothing else to worry about other than working with the files that display the watch face.

So with those things settled, let's start with the basics of a watchface.

Please remember that this is a wiki, so you can make an account and help us improve this page.

Please make sure not to unilaterally remove info though, but offer an alternative. If it is indeed a better way, in time your alternative will grow into the main text, and the latter info will be pruned.

==Overview==
The Firmware (also called InfiniTime) we will be working with is made with a programming language named '''C++''':[https://en.wikipedia.org/wiki/C%2B%2B]

Basic knowledge of C/C++ is required to to understand the advanced watch faces as that requires more complex code, but you can still do a some cool things without much knowledge of C++ programming, just some small edits to existing programs.

InfiniTime uses the '''LVGL''':[https://lvgl.io] graphics library to provide users with a simple and clean UI without overpowering the Nordic '''nRF52832''':[http://files.pine64.org/doc/datasheet/pinetime/nRF52832%20product%20brief.pdf] microcontroller which is the brain of the watch.

To get the watchface to work there are these basic steps. We will go over each step separately, so don't be daunted, all will become clear soon.

For now we will, modify the the existing watchface, change the positioning of the text labels, add an icon to an existing watchface, and later on we will do a full watchface.

The main file we need to focus on is the '''clock.cpp''' file, it is what contains most of the data attributed to what we see on the watchface, including The time/day characters, the battery and bluetooth icons, and also pedometer count...

so everything we will be doing in the basic modifications is purely messing with this single file.

==Labels==
===What are labels?===
Labels are considered as "elemental" parts that make up a screen's Text-based UI by the LVGL library...
Each label is also considered as an "object" or "obj" and can be manipulated, by changing the data attributed with the "obj", for example, position, internal data like the strings/text etc.
when can change what the label shows and where it shows it...

===Modifying label data===
let's observe something small like the word "BPM" near the bottom of the watch face...
[[file:PineTimeCustom-1.png|right|200px]]

If we take a look at the source file of the watchface, (a.k.a the clock.cpp file)
we can observe that these particular lines are what attributes to the word "BPM being displayed...
heartbeatBpm = lv_label_create(lv_scr_act(), NULL);
lv_label_set_text(heartbeatBpm, "BPM");

we can modify the text inside the quotes and replace the word 'BPM' between those quotes to something like 'LOVE'
and the result after compiling the firmware again with the changes and flashing it to the watch would be that the text changes on the watch face and displays 'LOVE' inplace of 'BPM'...

If this happened correctly, then you have successfully made a custom new watchface! Now we can do something a bit more complex...

Now take for in instance the days of the week that we have on the bottom line with the date...

they are stored a "C array" which is basically multiple words separated by commas..
the date is in a format of '''<day of the week> <day> <Month> <year>'''

which in the source file is expressed as,
sprintf(dateStr, "%s %d %s %d", DayOfWeekToString(dayOfWeek), day, MonthToString(month), year);
lv_label_set_text(label_date, dateStr);

here,
%s %d %s %d
stores the print format of the variables, and

DayOfWeekToString(dayOfWeek), day, MonthToString(month), year
are the variables themselves...

Now,
if the date was a saturday 11/7/2020, you can observe that the date looks like
SATURDAY 11 JUL 2020
as seen in the above image (the one where we changed BPM to LOVE)

by modifying the format of the variables, we can change how those words are arranged, and add some extra characters if we like...
(there is a catch to the list of characters you can use however, but it will be discussed later...)

For example,

We modifying the format by adding a comma... "," in between the second "%s" and "%d" like this,
"%s %d %s, %d"
and changing that in the line...
sprintf(dateStr, "%s %d %s, %d", DayOfWeekToString(dayOfWeek), day, MonthToString(month), year);

we can make the date become...
SATURDAY 11 JUL, 2020

which means we now were able to modify how the text got display to make it a bit more nice...

but if you haven't noticed, the line containing the date is already full, meaning we will get some problems while displaying the date and causing it to wrap around,
making a single character go to the next line and look more like,

SATURDAY 11 JUL, 202
0

so why don't we shorten the characters present in the date from being "SATURDAY" to simply just "sat." (It will have the small period at the end, and is only 3 characters long)
I will also convert the months of the year from Capital to small letters...

for that look into the part where the days of the week of are stored as text,
and also while looking at it, we can solve another question, why was their two variables in the date format that looked like, DayOfWeekToString(dayOfWeek), and MonthToString(month) ?

It is because the system gives the date/ time as numbers (Monday-1, Tuesday-2 Wednesday-3 for the days, and 1-January, 2-February, 3-March ),
and so a function along with a C array is used to assign these numbers to Days/Months in text form as it is easier to read...

this is the Array containing the day of the week, (as text)
char const *Clock::DaysString[] = {
"",
"MONDAY",
"TUESDAY",
"WEDNESDAY",
"THURSDAY",
"FRIDAY",
"SATURDAY",
"SUNDAY"
};

and this Array stores the months of the year, (as text)
char const *Clock::MonthsString[] = {
"",
"JAN",
"FEB",
"MAR",
"APR",
"MAY",
"JUN",
"JUL",
"AUG",
"SEP",
"OCT",
"NOV",
"DEC"
};

here we can see that the days are stored in a full format as "SUNDAY", "MONDAY", "TUESDAY" etc.
we can change all of them to a shorter format like "sun.", "mon.", "tue.", to make it short and nice...
while doing so, we can even make the months use small letters as said before..

so the source file (clock.cpp) becomes,

(for the days of the week)
char const *Clock::DaysString[] = {
"",
"mon.",
"tue.",
"wed.",
"thu.",
"fri.",
"sat.",
"sun."
};

and

(for the months of the year)
char const *Clock::MonthsString[] = {
"",
"jan",
"feb",
"mar",
"apr",
"may",
"jun",
"jul",
"aug",
"sep",
"oct",
"nov",
"dec"
};

which means now our original date, saturday 11/7/2020 will become...
sat. 11 jul, 2020

you now know how to change the data present in a label object, and the format of it..,

Here is a fun idea you can try: you can even replace the days with whatever thing that tells you (or) reminds you the day of the week
(like the food served in the cafe, Monday/taco, Tuesday/burger, Wednesday/pasta etc.)

NOTE: when making the custom array, don't forget to leave a empty "" as the first element of the array,
This is because the date is given by the system in a natural numbers format (1,2,3...) rather than a zero-starting format (0,1,2,3...), which the C array uses to index...
so the C array indexes the days as ""-0, "Monday"-1, "Tuesday"-2 etc. and the months as ""-0, "January"-1, "February"-2 etc.)

===Label positioning===

The locational placement in LVGL is done on a cartesian plane,
where each object can have dynamic origin placement, and the Y-axis is inverted...
So going down is done with a positive Y-axis value and not negative as the it is by de-facto...

The position of the various objects in clock.cpp are set by the line,
lv_obj_set_pos(<obj>, <new_x>, <new_y>)

and the top left corner is the Cartesian origin, aka coordinates (0,0)

we use another function, that is more advanced that gives the positional alignment based on preset locations...
lv_obj_align(<text/obj>, <image/obj>, <location_parameter>, <new_x>, <new_y>);

the "<image/obj>" data is used for putting text beside other picture icons , and so if using only text based labels, we can substitute it with,
lv_scr_act() (or) NULL

'''<new_x>, <new_y>''' are the cartesian coordinates, '''<location parameter>''' is replaced by '''LV_ALIGN_<preset>''',
there will be a picture showing the presets below, and '''<text/obj>''' is your text label...

here, LV_ALIGN_<preset> sets the cartesian origin...

Label positioning based on alignment is both a simple and complicated thing to understand, so here I have given something you can refer to while modifying the position of the various labels and objects...

you can also refer here for LVGL's documentation of coordinate system https://docs.lvgl.io/v6/en/html/object-types/obj.html#coordinates

It is however recommended that you use the first method to set the location
lv_obj_set_pos(<obj>, <new_x>, <new_y>)
as it is simple and easier for beginners

Here is a small example.

Take the Label that tells the date,
In the source file (clock.cpp) it is this line,
lv_obj_align(label_date, lv_scr_act(), LV_ALIGN_IN_LEFT_MID, 0, 60);
by increasing the Value of the Y coordinate (60) to a higher value, we can bring the position of the Date downwards a bit away from the Time, and toward the Heartbeat count in the bottom row
here I will increase it to 80, so it becomes..
lv_obj_align(label_date, lv_scr_act(), LV_ALIGN_IN_LEFT_MID, 0, 80);

and now we have made some space up top..

now let's try something a bit complex,

Take the position argument for the label that tells you time...
here, in the source file (clock.cpp),
lv_obj_align(label_time, lv_scr_act(), LV_ALIGN_IN_LEFT_MID, 0, 0);

this line determines the position of the Label telling time, as seen in the image...

we modifying this, by changing the origin <preset> parameter (here it is LV_ALIGN_IN_LEFT_MID) to LV_ALIGN_IN_TOP_LEFT

you can alternatively swap the whole line to,
lv_obj_set_pos(label_time, 0, 0);

this makes the Time label/obj. to go to the top left corner...

but I will do something a little extra,
I will modify the label that store the data and Time format,
i.e this line,
sprintf(timeStr, "%c%c:%c%c", hoursChar[0],hoursChar[1],minutesChar[0], minutesChar[1]);

by removing the ":" colon in between the numbers, and replacing it with a Newline symbol "\n"
I change it to become,
sprintf(timeStr, "%c%c\n%c%c", hoursChar[0],hoursChar[1],minutesChar[0], minutesChar[1]);

this gives it a nice wrapped text format in the top corner, and gives us some space to play with in the side, for things like Pictures and icons, which we will do next..

If you have been able to do these things, you now have completed the 2nd part of the tutorial, and now know how to change and modify the position of labels..

==Using icons==
The LVGL library allows for the use of widgets known as "Images", In short it allows you to use small Icons like pictures with a small dedicated function,
However when this was attempted the first time we stumbled on some problems as LVGL v6 (used on the pinetime) is not much documented as the latest release (v7 as of August 2020)
but also the existing code was only documented for C not C++, after some painful attempts we were able to translate it into C++,

To bring images into Clock.cpp
you will need to do the following,

1. Have a small image that cannot exceed a maximum size of 240px x 240px (pinetime max resolution)

2. Use this Image converter (Thanks to LVGL) https://lvgl.io/tools/imageconverter
to convert your image to a C array and having the Color format as "True color" and the output format as "C array"
make sure to use something simple as the name we will be using "bitmap" as the name, but will also be referred as <name> for simplicity

Note: for example we shall use <name> = bitmap, but any simple word can be used, as long as it does not cause problems with system variables

===Image size considerations===
since the image will be written from internal Flash to the RAM, we need to be considerate as to use less RAM as we are capped at 64KB maximum...
for testing we did not exceed more than 30% of the 64KB which is about 19.2KB...

You can calculate the RAM usage of your images with a simple formula..
<picture_X> x <picture_Y> x 2
give you the number of KB the image uses...
where, <picture_X> <picture_Y> are the dimensions of the image horizontally and vertically

for example,
if <picture_X>=80px <picture_Y>=64px
then,
total RAM used = 80 x 60 x 2 = 10.24KB

please use the RAM sparingly, too much and the RAM overflow could cause the MCU to crash... you have been warned !!!

==Preparing the image for inclusion as an icon==

Once you have your obtained your C array from the LVGL converter, you can take a look inside it to see all the different formats of your image,
try using something like Notepad++ or any of your favorite text editors to peek inside of it,

there will be 4 sets of Arrays inside it that look like,

#if LV_COLOR_DEPTH == 1 || LV_COLOR_DEPTH == 8
/*Pixel format: Red: 3 bit, Green: 3 bit, Blue: 2 bit*/
0x00, 0x00, 0x00,...
...0x00, 0x00, 0x00,
#endif

#if LV_COLOR_DEPTH == 16 && LV_COLOR_16_SWAP == 0
/*Pixel format: Red: 5 bit, Green: 6 bit, Blue: 5 bit*/
0x00, 0x00, 0x00,...
...0x00, 0x00, 0x00,
#endif

#if LV_COLOR_DEPTH == 16 && LV_COLOR_16_SWAP != 0
/*Pixel format: Red: 5 bit, Green: 6 bit, Blue: 5 bit BUT the 2 bytes are swapped*/
0x00, 0x00, 0x00,...
...0x00, 0x00, 0x00,
#endif

#if LV_COLOR_DEPTH == 32
/*Pixel format: Fix 0xFF: 8 bit, Red: 8 bit, Green: 8 bit, Blue: 8 bit*/
0x00, 0x00, 0x00,...
...0x00, 0x00, 0xff,
#endif
};

And another small bit of info we will need for later that looks like,

const lv_img_dsc_t bitmap = {
.header.always_zero = 0,
.header.w = 40,
.header.h = 40,
.data_size = 1600 * LV_COLOR_SIZE / 8,
.header.cf = LV_IMG_CF_TRUE_COLOR,
.data = bitmap_map,
};

NOTE: There are some header files at the top, which we can ignore...
===RGB565 image format===

The Pinetime uses a display that uses a 16 bit color space, also known as RGB565.

These 16 bit are assigned to RGB as 5 bits each for Red and Blue and 6 bits for Green, so 5+6+5=16 bits are required, so each pixel's color occupies 2 bytes of data,
and since 216 is equal to 65,536 it allows us to view 65,536 or 65k colors

The way it packs these bits is by converting the bits into 2x 4+4 bit hex-code, so for example,

if the color of a pixel in Binary is '''10110100 01011111''' (this color is approximately Lavender purple)

It is split as '''1011''' & '''0100''' for the first byte and '''0101''' & '''1111''' for the second byte
and so, converting the binary into Hex-code,

the two parts are '''0xB4''' and '''0xF5'''

These two parts in conjunction are used for determining the color of one pixel...

also from the binary, it is observed that,

The bits '''10110''' is used for Red, '''100010''' is used for green, and '''11111''' is used for blue.

===Flipping the bytes===
The LVGL library has a feature that allows you to flip the two bytes of the pixel, so if the two parts were, ...0xB4,0xF5,... ,it will change it to become, ...0xF5,0xB4,...

The reason for this is to allow the use of 8-bit SPI interfaces, but we do not require it, and if set with wrong parameter we could get problems with the color...

To make sure you are ready for the next step, make sure that inside your lvgl configuration file (located at '''src/libs/lv_conf.h''')

this parameter,
'''#define LV_COLOR_16_SWAP 1'''
is set to "1" as seen...

NOTE: if you haven't modified it or tampered with it with your Github fork, you shouldn't have a problem
as it is correct by default, and you can skip these steps

===Creating an Object from the Array===
To include the Icon, first Identify the Array you need to copy to the source (clock.cpp)

The one we require from it is the data below the tag that looks like,
#if LV_COLOR_DEPTH == 16 && LV_COLOR_16_SWAP != 0
/*Pixel format: Red: 5 bit, Green: 6 bit, Blue: 5 bit BUT the 2 bytes are swapped*/
0x00, 0x00, 0x00,...
...0x00, 0x00, 0x00,
#endif

from this copy the Data from the array alone...
I.e this part,
0x00, 0x00, 0x00,...
...0x00, 0x00, 0x00

(Make sure to not include the comma at the end or the #endif as the entire part is going to substitute a new array)

In clock.cpp, just below the header files and the Task creation part (I.e event_handler...),
create a name for the label with,
static lv_img_dsc_t <name>; // remember to replace <name> with the actual name you gave to your image while converting !

then below it create a array to hold the data with,
const uint8_t bitmap_map[] = {<data>}; // paste the array you copied from the conversion file we specified above...

Then inside the Clock::Clock(DisplayApp* app,...){... region,
You need to place a particular set of lines which LVGL uses to define the object declare the array as an Icon/Image, You can place this set of lines above label_time...

<name>.header.always_zero = 0; //Initialization
<name>.header.w = <picture_X>; // Setting the Width (or) Horizontal length of the image (number of px)
<name>.header.h = <picture_Y>; // Setting the Height (or) vertical length of the image (number of px)
<name>.data_size = <Hr_length> * <Vr_length> * LV_COLOR_SIZE / 8; //Allocation of memory for the image
<name>.header.cf = LV_IMG_CF_TRUE_COLOR; // Sets the color scheme for the image
<name>.data = <name>_map; // Maps the Image data to the Array
lv_obj_t *img_src = lv_img_create(lv_scr_act(), NULL); // Create an image object
lv_img_set_src(img_src, &<name>); // Set the created file as image (<name>)

again, make sure to replace <name> with the name you gave it during conversion!

Now that we have bought in the image data, we need to set the position, you can place this just below the lines we wrote for bringing in the image, It can be done with either,
lv_obj_set_pos(img_src, <x_pos, <y_pos>); // <x_pos>, <y_pos> are the coordinates of the cartesian plane
or,
lv_obj_align(img_src, lv_scr_act(), LV_ALIGN_<parameter>, <x_pos, <y_pos>);

If done correctly, you will now have a beautiful little Icon/Image in your Watch face,
Make sure that your Watch face can accommodate the Image by pushing the other labels farther away creating space for it...

We have provided a small template you can use for adding even a large image comfortably

If you have succeeded with this, you have completed part 3 of the tutorial.

=Using git to work on the firmware=
===Cloning the repository===
===Changing the code to add the image===
===Compiling the firmware===
==Testing the firmware==
===Installing the new firmware===

A holistic guide on how to install different firmware using various hardware programmers is available here: [[Reprogramming the PineTime]]. There's also the possibility of using OTA updating. ''//TODO: add that to the article!''

===Activating the firmware===
===How to troubleshoot===
==Conclusions==
==Next steps==
==More in-depth documentation==
==Thanks for the help==

PineTime Custom Watchface Tutorial

2020-08-17T09:16:52Z

Electr0lyte: /* RAM vs ROM */

=PineTime Custom Watchface Tutorial=

This is a tutorial to help new users create custom watchfaces based on the InfiniTime Firmware for Pinetime made by user JF002, thanks to him for its development...

We will explain some of the things we went through while creating some custom Watchfaces, so consider this as a log of experiments of sorts..

So stay tuned to it as it will be dynamically updated...

==What you need to start==
The entire building process will be done by GitHub, so all you need is a device which can give you a Github Web Client, a PC or tablet to give you enough screen space to review your code and a steady internet connection.

Since the compiling and file management is done by Github online, you have nothing else to worry about other than working with the files that display the watch face.

So with those things settled, let's start with the basics of a watchface.

Please remember that this is a wiki, so you can make an account and help us improve this page.

Please make sure not to unilaterally remove info though, but offer an alternative. If it is indeed a better way, in time your alternative will grow into the main text, and the latter info will be pruned.

==Overview==
The Firmware (also called InfiniTime) we will be working with is made with a programming language named '''C++''':[https://en.wikipedia.org/wiki/C%2B%2B]

Basic knowledge of C/C++ is required to to understand the advanced watch faces as that requires more complex code, but you can still do a some cool things without much knowledge of C++ programming, just some small edits to existing programs.

InfiniTime uses the '''LVGL''':[https://lvgl.io] graphics library to provide users with a simple and clean UI without overpowering the Nordic '''nRF52832''':[http://files.pine64.org/doc/datasheet/pinetime/nRF52832%20product%20brief.pdf] microcontroller which is the brain of the watch.

To get the watchface to work there are these basic steps. We will go over each step separately, so don't be daunted, all will become clear soon.

For now we will, modify the the existing watchface, change the positioning of the text labels, add an icon to an existing watchface, and later on we will do a full watchface.

The main file we need to focus on is the '''clock.cpp''' file, it is what contains most of the data attributed to what we see on the watchface, including The time/day characters, the battery and bluetooth icons, and also pedometer count...

so everything we will be doing in the basic modifications is purely messing with this single file.

==Labels==
===What are labels?===
Labels are considered as "elemental" parts that make up a screen's Text-based UI by the LVGL library...
Each label is also considered as an "object" or "obj" and can be manipulated, by changing the data attributed with the "obj", for example, position, internal data like the strings/text etc.
when can change what the label shows and where it shows it...

===Modifying label data===
let's observe something small like the word "BPM" near the bottom of the watch face...
[[file:PineTimeCustom-1.png|right|200px]]

If we take a look at the source file of the watchface, (a.k.a the clock.cpp file)
we can observe that these particular lines are what attributes to the word "BPM being displayed...
heartbeatBpm = lv_label_create(lv_scr_act(), NULL);
lv_label_set_text(heartbeatBpm, "BPM");

we can modify the text inside the quotes and replace the word 'BPM' between those quotes to something like 'LOVE'
and the result after compiling the firmware again with the changes and flashing it to the watch would be that the text changes on the watch face and displays 'LOVE' inplace of 'BPM'...

If this happened correctly, then you have successfully made a custom new watchface! Now we can do something a bit more complex...

Now take for in instance the days of the week that we have on the bottom line with the date...

they are stored a "C array" which is basically multiple words separated by commas..
the date is in a format of '''<day of the week> <day> <Month> <year>'''

which in the source file is expressed as,
sprintf(dateStr, "%s %d %s %d", DayOfWeekToString(dayOfWeek), day, MonthToString(month), year);
lv_label_set_text(label_date, dateStr);

here,
%s %d %s %d
stores the print format of the variables, and

DayOfWeekToString(dayOfWeek), day, MonthToString(month), year
are the variables themselves...

Now,
if the date was a saturday 11/7/2020, you can observe that the date looks like
SATURDAY 11 JUL 2020
as seen in the above image (the one where we changed BPM to LOVE)

by modifying the format of the variables, we can change how those words are arranged, and add some extra characters if we like...
(there is a catch to the list of characters you can use however, but it will be discussed later...)

For example,

We modifying the format by adding a comma... "," in between the second "%s" and "%d" like this,
"%s %d %s, %d"
and changing that in the line...
sprintf(dateStr, "%s %d %s, %d", DayOfWeekToString(dayOfWeek), day, MonthToString(month), year);

we can make the date become...
SATURDAY 11 JUL, 2020

which means we now were able to modify how the text got display to make it a bit more nice...

but if you haven't noticed, the line containing the date is already full, meaning we will get some problems while displaying the date and causing it to wrap around,
making a single character go to the next line and look more like,

SATURDAY 11 JUL, 202
0

so why don't we shorten the characters present in the date from being "SATURDAY" to simply just "sat." (It will have the small period at the end, and is only 3 characters long)
I will also convert the months of the year from Capital to small letters...

for that look into the part where the days of the week of are stored as text,
and also while looking at it, we can solve another question, why was their two variables in the date format that looked like, DayOfWeekToString(dayOfWeek), and MonthToString(month) ?

It is because the system gives the date/ time as numbers (Monday-1, Tuesday-2 Wednesday-3 for the days, and 1-January, 2-February, 3-March ),
and so a function along with a C array is used to assign these numbers to Days/Months in text form as it is easier to read...

this is the Array containing the day of the week, (as text)
char const *Clock::DaysString[] = {
"",
"MONDAY",
"TUESDAY",
"WEDNESDAY",
"THURSDAY",
"FRIDAY",
"SATURDAY",
"SUNDAY"
};

and this Array stores the months of the year, (as text)
char const *Clock::MonthsString[] = {
"",
"JAN",
"FEB",
"MAR",
"APR",
"MAY",
"JUN",
"JUL",
"AUG",
"SEP",
"OCT",
"NOV",
"DEC"
};

here we can see that the days are stored in a full format as "SUNDAY", "MONDAY", "TUESDAY" etc.
we can change all of them to a shorter format like "sun.", "mon.", "tue.", to make it short and nice...
while doing so, we can even make the months use small letters as said before..

so the source file (clock.cpp) becomes,

(for the days of the week)
char const *Clock::DaysString[] = {
"",
"mon.",
"tue.",
"wed.",
"thu.",
"fri.",
"sat.",
"sun."
};

and

(for the months of the year)
char const *Clock::MonthsString[] = {
"",
"jan",
"feb",
"mar",
"apr",
"may",
"jun",
"jul",
"aug",
"sep",
"oct",
"nov",
"dec"
};

which means now our original date, saturday 11/7/2020 will become...
sat. 11 jul, 2020

you now know how to change the data present in a label object, and the format of it..,

Here is a fun idea you can try: you can even replace the days with whatever thing that tells you (or) reminds you the day of the week
(like the food served in the cafe, Monday/taco, Tuesday/burger, Wednesday/pasta etc.)

NOTE: when making the custom array, don't forget to leave a empty "" as the first element of the array,
This is because the date is given by the system in a natural numbers format (1,2,3...) rather than a zero-starting format (0,1,2,3...), which the C array uses to index...
so the C array indexes the days as ""-0, "Monday"-1, "Tuesday"-2 etc. and the months as ""-0, "January"-1, "February"-2 etc.)

===Label positioning===

The locational placement in LVGL is done on a cartesian plane,
where each object can have dynamic origin placement, and the Y-axis is inverted...
So going down is done with a positive Y-axis value and not negative as the it is by de-facto...

The position of the various objects in clock.cpp are set by the line,
lv_obj_set_pos(<obj>, <new_x>, <new_y>)

and the top left corner is the Cartesian origin, aka coordinates (0,0)

we use another function, that is more advanced that gives the positional alignment based on preset locations...
lv_obj_align(<text/obj>, <image/obj>, <location_parameter>, <new_x>, <new_y>);

the "<image/obj>" data is used for putting text beside other picture icons , and so if using only text based labels, we can substitute it with,
lv_scr_act() (or) NULL

'''<new_x>, <new_y>''' are the cartesian coordinates, '''<location parameter>''' is replaced by '''LV_ALIGN_<preset>''',
there will be a picture showing the presets below, and '''<text/obj>''' is your text label...

here, LV_ALIGN_<preset> sets the cartesian origin...

Label positioning based on alignment is both a simple and complicated thing to understand, so here I have given something you can refer to while modifying the position of the various labels and objects...

you can also refer here for LVGL's documentation of coordinate system https://docs.lvgl.io/v6/en/html/object-types/obj.html#coordinates

It is however recommended that you use the first method to set the location
lv_obj_set_pos(<obj>, <new_x>, <new_y>)
as it is simple and easier for beginners

Here is a small example.

Take the Label that tells the date,
In the source file (clock.cpp) it is this line,
lv_obj_align(label_date, lv_scr_act(), LV_ALIGN_IN_LEFT_MID, 0, 60);
by increasing the Value of the Y coordinate (60) to a higher value, we can bring the position of the Date downwards a bit away from the Time, and toward the Heartbeat count in the bottom row
here I will increase it to 80, so it becomes..
lv_obj_align(label_date, lv_scr_act(), LV_ALIGN_IN_LEFT_MID, 0, 80);

and now we have made some space up top..

now let's try something a bit complex,

Take the position argument for the label that tells you time...
here, in the source file (clock.cpp),
lv_obj_align(label_time, lv_scr_act(), LV_ALIGN_IN_LEFT_MID, 0, 0);

this line determines the position of the Label telling time, as seen in the image...

we modifying this, by changing the origin <preset> parameter (here it is LV_ALIGN_IN_LEFT_MID) to LV_ALIGN_IN_TOP_LEFT

you can alternatively swap the whole line to,
lv_obj_set_pos(label_time, 0, 0);

this makes the Time label/obj. to go to the top left corner...

but I will do something a little extra,
I will modify the label that store the data and Time format,
i.e this line,
sprintf(timeStr, "%c%c:%c%c", hoursChar[0],hoursChar[1],minutesChar[0], minutesChar[1]);

by removing the ":" colon in between the numbers, and replacing it with a Newline symbol "\n"
I change it to become,
sprintf(timeStr, "%c%c\n%c%c", hoursChar[0],hoursChar[1],minutesChar[0], minutesChar[1]);

this gives it a nice wrapped text format in the top corner, and gives us some space to play with in the side, for things like Pictures and icons, which we will do next..

If you have been able to do these things, you now have completed the 2nd part of the tutorial, and now know how to change and modify the position of labels..

==Using icons==
The LVGL library allows for the use of widgets known as "Images", In short it allows you to use small Icons like pictures with a small dedicated function,
However when this was attempted the first time we stumbled on some problems as LVGL v6 (used on the pinetime) is not much documented as the latest release (v7 as of August 2020)
but also the existing code was only documented for C not C++, after some painful attempts we were able to translate it into C++,

To bring images into Clock.cpp
you will need to do the following,

1. Have a small image that cannot exceed a maximum size of 240px x 240px (pinetime max resolution)

2. Use this Image converter (Thanks to LVGL) https://lvgl.io/tools/imageconverter
to convert your image to a C array and having the Color format as "True color" and the output format as "C array"
make sure to use something simple as the name we will be using "bitmap" as the name, but will also be referred as <name> for simplicity

Note: for example we shall use <name> = bitmap, but any simple word can be used, as long as it does not cause problems with system variables

===Image size considerations===
since the image will be written from internal Flash to the RAM, we need to be considerate as to use less RAM as we are capped at 64KB maximum...
for testing we did not exceed more than 30% of the 64KB which is about 19.2KB...

You can calculate the RAM usage of your images with a simple formula..
<picture_X> x <picture_Y> x 2
give you the number of KB the image uses...
where, <picture_X> <picture_Y> are the dimensions of the image horizontally and vertically

for example,
if <picture_X>=80px <picture_Y>=64px
then,
total RAM used = 80 x 60 x 2 = 10.24KB

please use the RAM sparingly, too much and the RAM overflow could cause the MCU to crash... you have been warned !!!

==Preparing the image for inclusion as an icon==

Once you have your obtained your C array from the LVGL converter, you can take a look inside it to see all the different formats of your image,
try using something like Notepad++ or any of your favorite text editors to peek inside of it,

there will be 4 sets of Arrays inside it that look like,

#if LV_COLOR_DEPTH == 1 || LV_COLOR_DEPTH == 8
/*Pixel format: Red: 3 bit, Green: 3 bit, Blue: 2 bit*/
0x00, 0x00, 0x00,...
...0x00, 0x00, 0x00,
#endif

#if LV_COLOR_DEPTH == 16 && LV_COLOR_16_SWAP == 0
/*Pixel format: Red: 5 bit, Green: 6 bit, Blue: 5 bit*/
0x00, 0x00, 0x00,...
...0x00, 0x00, 0x00,
#endif

#if LV_COLOR_DEPTH == 16 && LV_COLOR_16_SWAP != 0
/*Pixel format: Red: 5 bit, Green: 6 bit, Blue: 5 bit BUT the 2 bytes are swapped*/
0x00, 0x00, 0x00,...
...0x00, 0x00, 0x00,
#endif

#if LV_COLOR_DEPTH == 32
/*Pixel format: Fix 0xFF: 8 bit, Red: 8 bit, Green: 8 bit, Blue: 8 bit*/
0x00, 0x00, 0x00,...
...0x00, 0x00, 0xff,
#endif
};

And another small bit of info we will need for later that looks like,

const lv_img_dsc_t bitmap = {
.header.always_zero = 0,
.header.w = 40,
.header.h = 40,
.data_size = 1600 * LV_COLOR_SIZE / 8,
.header.cf = LV_IMG_CF_TRUE_COLOR,
.data = bitmap_map,
};

NOTE: There are some header files at the top, which we can ignore...
===RGB565 image format===

The Pinetime uses a display that uses a 16 bit color space, also known as RGB565.

These 16 bit are assigned to RGB as 5 bits each for Red and Blue and 6 bits for Green, so 5+6+5=16 bits are required, so each pixel's color occupies 2 bytes of data,
and since 216 is equal to 65,536 it allows us to view 65,536 or 65k colors

The way it packs these bits is by converting the bits into 2x 4+4 bit hex-code, so for example,

if the color of a pixel in Binary is '''10110100 01011111''' (this color is approximately Lavender purple)

It is split as '''1011''' & '''0100''' for the first byte and '''0101''' & '''1111''' for the second byte
and so, converting the binary into Hex-code,

the two parts are '''0xB4''' and '''0xF5'''

These two parts in conjunction are used for determining the color of one pixel...

also from the binary, it is observed that,

The bits '''10110''' is used for Red, '''100010''' is used for green, and '''11111''' is used for blue.

===Flipping the bytes===
The LVGL library has a feature that allows you to flip the two bytes of the pixel, so if the two parts were, ...0xB4,0xF5,... ,it will change it to become, ...0xF5,0xB4,...

The reason for this is to allow the use of 8-bit SPI interfaces, but we do not require it, and if set with wrong parameter we could get problems with the color...

To make sure you are ready for the next step, make sure that inside your lvgl configuration file (located at '''src/libs/lv_conf.h''')

this parameter,
'''#define LV_COLOR_16_SWAP 0'''
is set to "0" as seen...

===Creating an Object from the Array===
To include the Icon, first Identify the Array you need to copy to the source (clock.cpp)

The one we require from it is the data below the tag that looks like,
#if LV_COLOR_DEPTH == 16 && LV_COLOR_16_SWAP != 0
/*Pixel format: Red: 5 bit, Green: 6 bit, Blue: 5 bit BUT the 2 bytes are swapped*/
0x00, 0x00, 0x00,...
...0x00, 0x00, 0x00,
#endif

from this copy the Data from the array alone...
I.e this part,
0x00, 0x00, 0x00,...
...0x00, 0x00, 0x00

(Make sure to not include the comma at the end or the #endif as the entire part is going to substitute a new array)

In clock.cpp, just below the header files and the Task creation part (I.e event_handler...),
create a name for the label with,
static lv_img_dsc_t <name>; // remember to replace <name> with the actual name you gave to your image while converting !

then below it create a array to hold the data with,
const uint8_t bitmap_map[] = {<data>}; // paste the array you copied from the conversion file we specified above...

Then inside the Clock::Clock(DisplayApp* app,...){... region,
You need to place a particular set of lines which LVGL uses to define the object declare the array as an Icon/Image, You can place this set of lines above label_time...

<name>.header.always_zero = 0; //Initialization
<name>.header.w = <picture_X>; // Setting the Width (or) Horizontal length of the image (number of px)
<name>.header.h = <picture_Y>; // Setting the Height (or) vertical length of the image (number of px)
<name>.data_size = <Hr_length> * <Vr_length> * LV_COLOR_SIZE / 8; //Allocation of memory for the image
<name>.header.cf = LV_IMG_CF_TRUE_COLOR; // Sets the color scheme for the image
<name>.data = <name>_map; // Maps the Image data to the Array
lv_obj_t *img_src = lv_img_create(lv_scr_act(), NULL); // Create an image object
lv_img_set_src(img_src, &<name>); // Set the created file as image (<name>)

again, make sure to replace <name> with the name you gave it during conversion!

Now that we have bought in the image data, we need to set the position, you can place this just below the lines we wrote for bringing in the image, It can be done with either,
lv_obj_set_pos(img_src, <x_pos, <y_pos>); // <x_pos>, <y_pos> are the coordinates of the cartesian plane
or,
lv_obj_align(img_src, lv_scr_act(), LV_ALIGN_<parameter>, <x_pos, <y_pos>);

If done correctly, you will now have a beautiful little Icon/Image in your Watch face,
Make sure that your Watch face can accommodate the Image by pushing the other labels farther away creating space for it...

We have provided a small template you can use for adding even a large image comfortably

If you have succeeded with this, you have completed part 3 of the tutorial.

=Using git to work on the firmware=
===Cloning the repository===
===Changing the code to add the image===
===Compiling the firmware===
==Testing the firmware==
===Installing the new firmware===

A holistic guide on how to install different firmware using various hardware programmers is available here: [[Reprogramming the PineTime]]. There's also the possibility of using OTA updating. ''//TODO: add that to the article!''

===Activating the firmware===
===How to troubleshoot===
==Conclusions==
==Next steps==
==More in-depth documentation==
==Thanks for the help==

PineTime Custom Watchface Tutorial

2020-08-17T08:17:10Z

Electr0lyte: /* Creating an Object from the Array */

=PineTime Custom Watchface Tutorial=

This is a tutorial to help new users create custom watchfaces based on the InfiniTime Firmware for Pinetime made by user JF002, thanks to him for its development...

We will explain some of the things we went through while creating some custom Watchfaces, so consider this as a log of experiments of sorts..

So stay tuned to it as it will be dynamically updated...

==What you need to start==
The entire building process will be done by GitHub, so all you need is a device which can give you a Github Web Client, a PC or tablet to give you enough screen space to review your code and a steady internet connection.

Since the compiling and file management is done by Github online, you have nothing else to worry about other than working with the files that display the watch face.

So with those things settled, let's start with the basics of a watchface.

Please remember that this is a wiki, so you can make an account and help us improve this page.

Please make sure not to unilaterally remove info though, but offer an alternative. If it is indeed a better way, in time your alternative will grow into the main text, and the latter info will be pruned.

==Overview==
The Firmware (also called InfiniTime) we will be working with is made with a programming language named '''C++''':[https://en.wikipedia.org/wiki/C%2B%2B]

Basic knowledge of C/C++ is required to to understand the advanced watch faces as that requires more complex code, but you can still do a some cool things without much knowledge of C++ programming, just some small edits to existing programs.

InfiniTime uses the '''LVGL''':[https://lvgl.io] graphics library to provide users with a simple and clean UI without overpowering the Nordic '''nRF52832''':[http://files.pine64.org/doc/datasheet/pinetime/nRF52832%20product%20brief.pdf] microcontroller which is the brain of the watch.

To get the watchface to work there are these basic steps. We will go over each step separately, so don't be daunted, all will become clear soon.

For now we will, modify the the existing watchface, change the positioning of the text labels, add an icon to an existing watchface, and later on we will do a full watchface.

The main file we need to focus on is the '''clock.cpp''' file, it is what contains most of the data attributed to what we see on the watchface, including The time/day characters, the battery and bluetooth icons, and also pedometer count...

so everything we will be doing in the basic modifications is purely messing with this single file.

==Labels==
===What are labels?===
Labels are considered as "elemental" parts that make up a screen's Text-based UI by the LVGL library...
Each label is also considered as an "object" or "obj" and can be manipulated, by changing the data attributed with the "obj", for example, position, internal data like the strings/text etc.
when can change what the label shows and where it shows it...

===Modifying label data===
let's observe something small like the word "BPM" near the bottom of the watch face...
[[file:PineTimeCustom-1.png|right|200px]]

If we take a look at the source file of the watchface, (a.k.a the clock.cpp file)
we can observe that these particular lines are what attributes to the word "BPM being displayed...
heartbeatBpm = lv_label_create(lv_scr_act(), NULL);
lv_label_set_text(heartbeatBpm, "BPM");

we can modify the text inside the quotes and replace the word 'BPM' between those quotes to something like 'LOVE'
and the result after compiling the firmware again with the changes and flashing it to the watch would be that the text changes on the watch face and displays 'LOVE' inplace of 'BPM'...

If this happened correctly, then you have successfully made a custom new watchface! Now we can do something a bit more complex...

Now take for in instance the days of the week that we have on the bottom line with the date...

they are stored a "C array" which is basically multiple words separated by commas..
the date is in a format of '''<day of the week> <day> <Month> <year>'''

which in the source file is expressed as,
sprintf(dateStr, "%s %d %s %d", DayOfWeekToString(dayOfWeek), day, MonthToString(month), year);
lv_label_set_text(label_date, dateStr);

here,
%s %d %s %d
stores the print format of the variables, and

DayOfWeekToString(dayOfWeek), day, MonthToString(month), year
are the variables themselves...

Now,
if the date was a saturday 11/7/2020, you can observe that the date looks like
SATURDAY 11 JUL 2020
as seen in the above image (the one where we changed BPM to LOVE)

by modifying the format of the variables, we can change how those words are arranged, and add some extra characters if we like...
(there is a catch to the list of characters you can use however, but it will be discussed later...)

For example,

We modifying the format by adding a comma... "," in between the second "%s" and "%d" like this,
"%s %d %s, %d"
and changing that in the line...
sprintf(dateStr, "%s %d %s, %d", DayOfWeekToString(dayOfWeek), day, MonthToString(month), year);

we can make the date become...
SATURDAY 11 JUL, 2020

which means we now were able to modify how the text got display to make it a bit more nice...

but if you haven't noticed, the line containing the date is already full, meaning we will get some problems while displaying the date and causing it to wrap around,
making a single character go to the next line and look more like,

SATURDAY 11 JUL, 202
0

so why don't we shorten the characters present in the date from being "SATURDAY" to simply just "sat." (It will have the small period at the end, and is only 3 characters long)
I will also convert the months of the year from Capital to small letters...

for that look into the part where the days of the week of are stored as text,
and also while looking at it, we can solve another question, why was their two variables in the date format that looked like, DayOfWeekToString(dayOfWeek), and MonthToString(month) ?

It is because the system gives the date/ time as numbers (Monday-1, Tuesday-2 Wednesday-3 for the days, and 1-January, 2-February, 3-March ),
and so a function along with a C array is used to assign these numbers to Days/Months in text form as it is easier to read...

this is the Array containing the day of the week, (as text)
char const *Clock::DaysString[] = {
"",
"MONDAY",
"TUESDAY",
"WEDNESDAY",
"THURSDAY",
"FRIDAY",
"SATURDAY",
"SUNDAY"
};

and this Array stores the months of the year, (as text)
char const *Clock::MonthsString[] = {
"",
"JAN",
"FEB",
"MAR",
"APR",
"MAY",
"JUN",
"JUL",
"AUG",
"SEP",
"OCT",
"NOV",
"DEC"
};

here we can see that the days are stored in a full format as "SUNDAY", "MONDAY", "TUESDAY" etc.
we can change all of them to a shorter format like "sun.", "mon.", "tue.", to make it short and nice...
while doing so, we can even make the months use small letters as said before..

so the source file (clock.cpp) becomes,

(for the days of the week)
char const *Clock::DaysString[] = {
"",
"mon.",
"tue.",
"wed.",
"thu.",
"fri.",
"sat.",
"sun."
};

and

(for the months of the year)
char const *Clock::MonthsString[] = {
"",
"jan",
"feb",
"mar",
"apr",
"may",
"jun",
"jul",
"aug",
"sep",
"oct",
"nov",
"dec"
};

which means now our original date, saturday 11/7/2020 will become...
sat. 11 jul, 2020

you now know how to change the data present in a label object, and the format of it..,

Here is a fun idea you can try: you can even replace the days with whatever thing that tells you (or) reminds you the day of the week
(like the food served in the cafe, Monday/taco, Tuesday/burger, Wednesday/pasta etc.)

NOTE: when making the custom array, don't forget to leave a empty "" as the first element of the array,
This is because the date is given by the system in a natural numbers format (1,2,3...) rather than a zero-starting format (0,1,2,3...), which the C array uses to index...
so the C array indexes the days as ""-0, "Monday"-1, "Tuesday"-2 etc. and the months as ""-0, "January"-1, "February"-2 etc.)

===Label positioning===

The locational placement in LVGL is done on a cartesian plane,
where each object can have dynamic origin placement, and the Y-axis is inverted...
So going down is done with a positive Y-axis value and not negative as the it is by de-facto...

The position of the various objects in clock.cpp are set by the line,
lv_obj_set_pos(<obj>, <new_x>, <new_y>)

and the top left corner is the Cartesian origin, aka coordinates (0,0)

we use another function, that is more advanced that gives the positional alignment based on preset locations...
lv_obj_align(<text/obj>, <image/obj>, <location_parameter>, <new_x>, <new_y>);

the "<image/obj>" data is used for putting text beside other picture icons , and so if using only text based labels, we can substitute it with,
lv_scr_act() (or) NULL

'''<new_x>, <new_y>''' are the cartesian coordinates, '''<location parameter>''' is replaced by '''LV_ALIGN_<preset>''',
there will be a picture showing the presets below, and '''<text/obj>''' is your text label...

here, LV_ALIGN_<preset> sets the cartesian origin...

Label positioning based on alignment is both a simple and complicated thing to understand, so here I have given something you can refer to while modifying the position of the various labels and objects...

you can also refer here for LVGL's documentation of coordinate system https://docs.lvgl.io/v6/en/html/object-types/obj.html#coordinates

It is however recommended that you use the first method to set the location
lv_obj_set_pos(<obj>, <new_x>, <new_y>)
as it is simple and easier for beginners

Here is a small example.

Take the Label that tells the date,
In the source file (clock.cpp) it is this line,
lv_obj_align(label_date, lv_scr_act(), LV_ALIGN_IN_LEFT_MID, 0, 60);
by increasing the Value of the Y coordinate (60) to a higher value, we can bring the position of the Date downwards a bit away from the Time, and toward the Heartbeat count in the bottom row
here I will increase it to 80, so it becomes..
lv_obj_align(label_date, lv_scr_act(), LV_ALIGN_IN_LEFT_MID, 0, 80);

and now we have made some space up top..

now let's try something a bit complex,

Take the position argument for the label that tells you time...
here, in the source file (clock.cpp),
lv_obj_align(label_time, lv_scr_act(), LV_ALIGN_IN_LEFT_MID, 0, 0);

this line determines the position of the Label telling time, as seen in the image...

we modifying this, by changing the origin <preset> parameter (here it is LV_ALIGN_IN_LEFT_MID) to LV_ALIGN_IN_TOP_LEFT

you can alternatively swap the whole line to,
lv_obj_set_pos(label_time, 0, 0);

this makes the Time label/obj. to go to the top left corner...

but I will do something a little extra,
I will modify the label that store the data and Time format,
i.e this line,
sprintf(timeStr, "%c%c:%c%c", hoursChar[0],hoursChar[1],minutesChar[0], minutesChar[1]);

by removing the ":" colon in between the numbers, and replacing it with a Newline symbol "\n"
I change it to become,
sprintf(timeStr, "%c%c\n%c%c", hoursChar[0],hoursChar[1],minutesChar[0], minutesChar[1]);

this gives it a nice wrapped text format in the top corner, and gives us some space to play with in the side, for things like Pictures and icons, which we will do next..

If you have been able to do these things, you now have completed the 2nd part of the tutorial, and now know how to change and modify the position of labels..

==Using icons==
The LVGL library allows for the use of widgets known as "Images", In short it allows you to use small Icons like pictures with a small dedicated function,
However when this was attempted the first time we stumbled on some problems as LVGL v6 (used on the pinetime) is not much documented as the latest release (v7 as of August 2020)
but also the existing code was only documented for C not C++, after some painful attempts we were able to translate it into C++,

To bring images into Clock.cpp
you will need to do the following,

1. Have a small image that cannot exceed a maximum size of 240px x 240px (pinetime max resolution)

2. Use this Image converter (Thanks to LVGL) https://lvgl.io/tools/imageconverter
to convert your image to a C array and having the Color format as "True color" and the output format as "C array"
make sure to use something simple as the name we will be using "bitmap" as the name, but will also be referred as <name> for simplicity

Note: for example we shall use <name> = bitmap, but any simple word can be used, as long as it does not cause problems with system variables

===Image size considerations===
since the image will be written from internal Flash to the RAM, we need to be considerate as to use less RAM as we are capped at 64KB maximum...
for testing we did not exceed more than 30% of the 64KB which is about 19.2KB...

You can calculate the RAM usage of your images with a simple formula..
<picture_X> x <picture_Y> x 2
give you the number of KB the image uses...
where, <picture_X> <picture_Y> are the dimensions of the image horizontally and vertically

for example,
if <picture_X>=80px <picture_Y>=64px
then,
total RAM used = 80 x 60 x 2 = 10.24KB

please use the RAM sparingly, too much and the RAM overflow could cause the MCU to crash... you have been warned !!!

==Preparing the image for inclusion as an icon==

Once you have your obtained your C array from the LVGL converter, you can take a look inside it to see all the different formats of your image,
try using something like Notepad++ or any of your favorite text editors to peek inside of it,

there will be 4 sets of Arrays inside it that look like,

#if LV_COLOR_DEPTH == 1 || LV_COLOR_DEPTH == 8
/*Pixel format: Red: 3 bit, Green: 3 bit, Blue: 2 bit*/
0x00, 0x00, 0x00,...
...0x00, 0x00, 0x00,
#endif

#if LV_COLOR_DEPTH == 16 && LV_COLOR_16_SWAP == 0
/*Pixel format: Red: 5 bit, Green: 6 bit, Blue: 5 bit*/
0x00, 0x00, 0x00,...
...0x00, 0x00, 0x00,
#endif

#if LV_COLOR_DEPTH == 16 && LV_COLOR_16_SWAP != 0
/*Pixel format: Red: 5 bit, Green: 6 bit, Blue: 5 bit BUT the 2 bytes are swapped*/
0x00, 0x00, 0x00,...
...0x00, 0x00, 0x00,
#endif

#if LV_COLOR_DEPTH == 32
/*Pixel format: Fix 0xFF: 8 bit, Red: 8 bit, Green: 8 bit, Blue: 8 bit*/
0x00, 0x00, 0x00,...
...0x00, 0x00, 0xff,
#endif
};

And another small bit of info we will need for later that looks like,

const lv_img_dsc_t bitmap = {
.header.always_zero = 0,
.header.w = 40,
.header.h = 40,
.data_size = 1600 * LV_COLOR_SIZE / 8,
.header.cf = LV_IMG_CF_TRUE_COLOR,
.data = bitmap_map,
};

NOTE: There are some header files at the top, which we can ignore...
===RGB565 image format===

The Pinetime uses a display that uses a 16 bit color space, also known as RGB565.

These 16 bit are assigned to RGB as 5 bits each for Red and Blue and 6 bits for Green, so 5+6+5=16 bits are required, so each pixel's color occupies 2 bytes of data,
and since 216 is equal to 65,536 it allows us to view 65,536 or 65k colors

The way it packs these bits is by converting the bits into 2x 4+4 bit hex-code, so for example,

if the color of a pixel in Binary is '''10110100 01011111''' (this color is approximately Lavender purple)

It is split as '''1011''' & '''0100''' for the first byte and '''0101''' & '''1111''' for the second byte
and so, converting the binary into Hex-code,

the two parts are '''0xB4''' and '''0xF5'''

These two parts in conjunction are used for determining the color of one pixel...

also from the binary, it is observed that,

The bits '''10110''' is used for Red, '''100010''' is used for green, and '''11111''' is used for blue.

===Flipping the bytes===
The LVGL library has a feature that allows you to flip the two bytes of the pixel, so if the two parts were, ...0xB4,0xF5,... ,it will change it to become, ...0xF5,0xB4,...

The reason for this is to allow the use of 8-bit SPI interfaces, but we do not require it, and if set with wrong parameter we could get problems with the color...

To make sure you are ready for the next step, make sure that inside your lvgl configuration file (located at '''src/libs/lv_conf.h''')

this parameter,
'''#define LV_COLOR_16_SWAP 0'''
is set to "0" as seen...

===Creating an Object from the Array===
To include the Icon, first Identify the Array you need to copy to the source (clock.cpp)

The one we require from it is the data below the tag that looks like,
#if LV_COLOR_DEPTH == 16 && LV_COLOR_16_SWAP != 0
/*Pixel format: Red: 5 bit, Green: 6 bit, Blue: 5 bit BUT the 2 bytes are swapped*/
0x00, 0x00, 0x00,...
...0x00, 0x00, 0x00,
#endif

from this copy the Data from the array alone...
I.e this part,
0x00, 0x00, 0x00,...
...0x00, 0x00, 0x00

(Make sure to not include the comma at the end or the #endif as the entire part is going to substitute a new array)

In clock.cpp, just below the header files and the Task creation part (I.e event_handler...),
create a name for the label with,
static lv_img_dsc_t <name>; // remember to replace <name> with the actual name you gave to your image while converting !

then below it create a array to hold the data with,
const uint8_t bitmap_map[] = {<data>}; // paste the array you copied from the conversion file we specified above...

Then inside the Clock::Clock(DisplayApp* app,...){... region,
You need to place a particular set of lines which LVGL uses to define the object declare the array as an Icon/Image, You can place this set of lines above label_time...

<name>.header.always_zero = 0; //Initialization
<name>.header.w = <picture_X>; // Setting the Width (or) Horizontal length of the image (number of px)
<name>.header.h = <picture_Y>; // Setting the Height (or) vertical length of the image (number of px)
<name>.data_size = <Hr_length> * <Vr_length> * LV_COLOR_SIZE / 8; //Allocation of memory for the image
<name>.header.cf = LV_IMG_CF_TRUE_COLOR; // Sets the color scheme for the image
<name>.data = <name>_map; // Maps the Image data to the Array
lv_obj_t *img_src = lv_img_create(lv_scr_act(), NULL); // Create an image object
lv_img_set_src(img_src, &<name>); // Set the created file as image (<name>)

again, make sure to replace <name> with the name you gave it during conversion!

Now that we have bought in the image data, we need to set the position, you can place this just below the lines we wrote for bringing in the image, It can be done with either,
lv_obj_set_pos(img_src, <x_pos, <y_pos>); // <x_pos>, <y_pos> are the coordinates of the cartesian plane
or,
lv_obj_align(img_src, lv_scr_act(), LV_ALIGN_<parameter>, <x_pos, <y_pos>);

If done correctly, you will now have a beautiful little Icon/Image in your Watch face,
Make sure that your Watch face can accommodate the Image by pushing the other labels farther away creating space for it...

We have provided a small template you can use for adding even a large image comfortably

If you have succeeded with this, you have completed part 3 of the tutorial.

===RAM vs ROM===

=Using git to work on the firmware=
===Cloning the repository===
===Changing the code to add the image===
===Compiling the firmware===
==Testing the firmware==
===Installing the new firmware===

A holistic guide on how to install different firmware using various hardware programmers is available here: [[Reprogramming the PineTime]]. There's also the possibility of using OTA updating. ''//TODO: add that to the article!''

===Activating the firmware===
===How to troubleshoot===
==Conclusions==
==Next steps==
==More in-depth documentation==
==Thanks for the help==

PineTime Custom Watchface Tutorial

2020-08-17T08:02:12Z

Electr0lyte: /* Creating an Object from the Array */

=PineTime Custom Watchface Tutorial=

This is a tutorial to help new users create custom watchfaces based on the InfiniTime Firmware for Pinetime made by user JF002, thanks to him for its development...

We will explain some of the things we went through while creating some custom Watchfaces, so consider this as a log of experiments of sorts..

So stay tuned to it as it will be dynamically updated...

==What you need to start==
The entire building process will be done by GitHub, so all you need is a device which can give you a Github Web Client, a PC or tablet to give you enough screen space to review your code and a steady internet connection.

Since the compiling and file management is done by Github online, you have nothing else to worry about other than working with the files that display the watch face.

So with those things settled, let's start with the basics of a watchface.

Please remember that this is a wiki, so you can make an account and help us improve this page.

Please make sure not to unilaterally remove info though, but offer an alternative. If it is indeed a better way, in time your alternative will grow into the main text, and the latter info will be pruned.

==Overview==
The Firmware (also called InfiniTime) we will be working with is made with a programming language named '''C++''':[https://en.wikipedia.org/wiki/C%2B%2B]

Basic knowledge of C/C++ is required to to understand the advanced watch faces as that requires more complex code, but you can still do a some cool things without much knowledge of C++ programming, just some small edits to existing programs.

InfiniTime uses the '''LVGL''':[https://lvgl.io] graphics library to provide users with a simple and clean UI without overpowering the Nordic '''nRF52832''':[http://files.pine64.org/doc/datasheet/pinetime/nRF52832%20product%20brief.pdf] microcontroller which is the brain of the watch.

To get the watchface to work there are these basic steps. We will go over each step separately, so don't be daunted, all will become clear soon.

For now we will, modify the the existing watchface, change the positioning of the text labels, add an icon to an existing watchface, and later on we will do a full watchface.

The main file we need to focus on is the '''clock.cpp''' file, it is what contains most of the data attributed to what we see on the watchface, including The time/day characters, the battery and bluetooth icons, and also pedometer count...

so everything we will be doing in the basic modifications is purely messing with this single file.

==Labels==
===What are labels?===
Labels are considered as "elemental" parts that make up a screen's Text-based UI by the LVGL library...
Each label is also considered as an "object" or "obj" and can be manipulated, by changing the data attributed with the "obj", for example, position, internal data like the strings/text etc.
when can change what the label shows and where it shows it...

===Modifying label data===
let's observe something small like the word "BPM" near the bottom of the watch face...
[[file:PineTimeCustom-1.png|right|200px]]

If we take a look at the source file of the watchface, (a.k.a the clock.cpp file)
we can observe that these particular lines are what attributes to the word "BPM being displayed...
heartbeatBpm = lv_label_create(lv_scr_act(), NULL);
lv_label_set_text(heartbeatBpm, "BPM");

we can modify the text inside the quotes and replace the word 'BPM' between those quotes to something like 'LOVE'
and the result after compiling the firmware again with the changes and flashing it to the watch would be that the text changes on the watch face and displays 'LOVE' inplace of 'BPM'...

If this happened correctly, then you have successfully made a custom new watchface! Now we can do something a bit more complex...

Now take for in instance the days of the week that we have on the bottom line with the date...

they are stored a "C array" which is basically multiple words separated by commas..
the date is in a format of '''<day of the week> <day> <Month> <year>'''

which in the source file is expressed as,
sprintf(dateStr, "%s %d %s %d", DayOfWeekToString(dayOfWeek), day, MonthToString(month), year);
lv_label_set_text(label_date, dateStr);

here,
%s %d %s %d
stores the print format of the variables, and

DayOfWeekToString(dayOfWeek), day, MonthToString(month), year
are the variables themselves...

Now,
if the date was a saturday 11/7/2020, you can observe that the date looks like
SATURDAY 11 JUL 2020
as seen in the above image (the one where we changed BPM to LOVE)

by modifying the format of the variables, we can change how those words are arranged, and add some extra characters if we like...
(there is a catch to the list of characters you can use however, but it will be discussed later...)

For example,

We modifying the format by adding a comma... "," in between the second "%s" and "%d" like this,
"%s %d %s, %d"
and changing that in the line...
sprintf(dateStr, "%s %d %s, %d", DayOfWeekToString(dayOfWeek), day, MonthToString(month), year);

we can make the date become...
SATURDAY 11 JUL, 2020

which means we now were able to modify how the text got display to make it a bit more nice...

but if you haven't noticed, the line containing the date is already full, meaning we will get some problems while displaying the date and causing it to wrap around,
making a single character go to the next line and look more like,

SATURDAY 11 JUL, 202
0

so why don't we shorten the characters present in the date from being "SATURDAY" to simply just "sat." (It will have the small period at the end, and is only 3 characters long)
I will also convert the months of the year from Capital to small letters...

for that look into the part where the days of the week of are stored as text,
and also while looking at it, we can solve another question, why was their two variables in the date format that looked like, DayOfWeekToString(dayOfWeek), and MonthToString(month) ?

It is because the system gives the date/ time as numbers (Monday-1, Tuesday-2 Wednesday-3 for the days, and 1-January, 2-February, 3-March ),
and so a function along with a C array is used to assign these numbers to Days/Months in text form as it is easier to read...

this is the Array containing the day of the week, (as text)
char const *Clock::DaysString[] = {
"",
"MONDAY",
"TUESDAY",
"WEDNESDAY",
"THURSDAY",
"FRIDAY",
"SATURDAY",
"SUNDAY"
};

and this Array stores the months of the year, (as text)
char const *Clock::MonthsString[] = {
"",
"JAN",
"FEB",
"MAR",
"APR",
"MAY",
"JUN",
"JUL",
"AUG",
"SEP",
"OCT",
"NOV",
"DEC"
};

here we can see that the days are stored in a full format as "SUNDAY", "MONDAY", "TUESDAY" etc.
we can change all of them to a shorter format like "sun.", "mon.", "tue.", to make it short and nice...
while doing so, we can even make the months use small letters as said before..

so the source file (clock.cpp) becomes,

(for the days of the week)
char const *Clock::DaysString[] = {
"",
"mon.",
"tue.",
"wed.",
"thu.",
"fri.",
"sat.",
"sun."
};

and

(for the months of the year)
char const *Clock::MonthsString[] = {
"",
"jan",
"feb",
"mar",
"apr",
"may",
"jun",
"jul",
"aug",
"sep",
"oct",
"nov",
"dec"
};

which means now our original date, saturday 11/7/2020 will become...
sat. 11 jul, 2020

you now know how to change the data present in a label object, and the format of it..,

Here is a fun idea you can try: you can even replace the days with whatever thing that tells you (or) reminds you the day of the week
(like the food served in the cafe, Monday/taco, Tuesday/burger, Wednesday/pasta etc.)

NOTE: when making the custom array, don't forget to leave a empty "" as the first element of the array,
This is because the date is given by the system in a natural numbers format (1,2,3...) rather than a zero-starting format (0,1,2,3...), which the C array uses to index...
so the C array indexes the days as ""-0, "Monday"-1, "Tuesday"-2 etc. and the months as ""-0, "January"-1, "February"-2 etc.)

===Label positioning===

The locational placement in LVGL is done on a cartesian plane,
where each object can have dynamic origin placement, and the Y-axis is inverted...
So going down is done with a positive Y-axis value and not negative as the it is by de-facto...

The position of the various objects in clock.cpp are set by the line,
lv_obj_set_pos(<obj>, <new_x>, <new_y>)

and the top left corner is the Cartesian origin, aka coordinates (0,0)

we use another function, that is more advanced that gives the positional alignment based on preset locations...
lv_obj_align(<text/obj>, <image/obj>, <location_parameter>, <new_x>, <new_y>);

the "<image/obj>" data is used for putting text beside other picture icons , and so if using only text based labels, we can substitute it with,
lv_scr_act() (or) NULL

'''<new_x>, <new_y>''' are the cartesian coordinates, '''<location parameter>''' is replaced by '''LV_ALIGN_<preset>''',
there will be a picture showing the presets below, and '''<text/obj>''' is your text label...

here, LV_ALIGN_<preset> sets the cartesian origin...

Label positioning based on alignment is both a simple and complicated thing to understand, so here I have given something you can refer to while modifying the position of the various labels and objects...

you can also refer here for LVGL's documentation of coordinate system https://docs.lvgl.io/v6/en/html/object-types/obj.html#coordinates

It is however recommended that you use the first method to set the location
lv_obj_set_pos(<obj>, <new_x>, <new_y>)
as it is simple and easier for beginners

Here is a small example.

Take the Label that tells the date,
In the source file (clock.cpp) it is this line,
lv_obj_align(label_date, lv_scr_act(), LV_ALIGN_IN_LEFT_MID, 0, 60);
by increasing the Value of the Y coordinate (60) to a higher value, we can bring the position of the Date downwards a bit away from the Time, and toward the Heartbeat count in the bottom row
here I will increase it to 80, so it becomes..
lv_obj_align(label_date, lv_scr_act(), LV_ALIGN_IN_LEFT_MID, 0, 80);

and now we have made some space up top..

now let's try something a bit complex,

Take the position argument for the label that tells you time...
here, in the source file (clock.cpp),
lv_obj_align(label_time, lv_scr_act(), LV_ALIGN_IN_LEFT_MID, 0, 0);

this line determines the position of the Label telling time, as seen in the image...

we modifying this, by changing the origin <preset> parameter (here it is LV_ALIGN_IN_LEFT_MID) to LV_ALIGN_IN_TOP_LEFT

you can alternatively swap the whole line to,
lv_obj_set_pos(label_time, 0, 0);

this makes the Time label/obj. to go to the top left corner...

but I will do something a little extra,
I will modify the label that store the data and Time format,
i.e this line,
sprintf(timeStr, "%c%c:%c%c", hoursChar[0],hoursChar[1],minutesChar[0], minutesChar[1]);

by removing the ":" colon in between the numbers, and replacing it with a Newline symbol "\n"
I change it to become,
sprintf(timeStr, "%c%c\n%c%c", hoursChar[0],hoursChar[1],minutesChar[0], minutesChar[1]);

this gives it a nice wrapped text format in the top corner, and gives us some space to play with in the side, for things like Pictures and icons, which we will do next..

If you have been able to do these things, you now have completed the 2nd part of the tutorial, and now know how to change and modify the position of labels..

==Using icons==
The LVGL library allows for the use of widgets known as "Images", In short it allows you to use small Icons like pictures with a small dedicated function,
However when this was attempted the first time we stumbled on some problems as LVGL v6 (used on the pinetime) is not much documented as the latest release (v7 as of August 2020)
but also the existing code was only documented for C not C++, after some painful attempts we were able to translate it into C++,

To bring images into Clock.cpp
you will need to do the following,

1. Have a small image that cannot exceed a maximum size of 240px x 240px (pinetime max resolution)

2. Use this Image converter (Thanks to LVGL) https://lvgl.io/tools/imageconverter
to convert your image to a C array and having the Color format as "True color" and the output format as "C array"
make sure to use something simple as the name we will be using "bitmap" as the name, but will also be referred as <name> for simplicity

Note: for example we shall use <name> = bitmap, but any simple word can be used, as long as it does not cause problems with system variables

===Image size considerations===
since the image will be written from internal Flash to the RAM, we need to be considerate as to use less RAM as we are capped at 64KB maximum...
for testing we did not exceed more than 30% of the 64KB which is about 19.2KB...

You can calculate the RAM usage of your images with a simple formula..
<picture_X> x <picture_Y> x 2
give you the number of KB the image uses...
where, <picture_X> <picture_Y> are the dimensions of the image horizontally and vertically

for example,
if <picture_X>=80px <picture_Y>=64px
then,
total RAM used = 80 x 60 x 2 = 10.24KB

please use the RAM sparingly, too much and the RAM overflow could cause the MCU to crash... you have been warned !!!

==Preparing the image for inclusion as an icon==

Once you have your obtained your C array from the LVGL converter, you can take a look inside it to see all the different formats of your image,
try using something like Notepad++ or any of your favorite text editors to peek inside of it,

there will be 4 sets of Arrays inside it that look like,

#if LV_COLOR_DEPTH == 1 || LV_COLOR_DEPTH == 8
/*Pixel format: Red: 3 bit, Green: 3 bit, Blue: 2 bit*/
0x00, 0x00, 0x00,...
...0x00, 0x00, 0x00,
#endif

#if LV_COLOR_DEPTH == 16 && LV_COLOR_16_SWAP == 0
/*Pixel format: Red: 5 bit, Green: 6 bit, Blue: 5 bit*/
0x00, 0x00, 0x00,...
...0x00, 0x00, 0x00,
#endif

#if LV_COLOR_DEPTH == 16 && LV_COLOR_16_SWAP != 0
/*Pixel format: Red: 5 bit, Green: 6 bit, Blue: 5 bit BUT the 2 bytes are swapped*/
0x00, 0x00, 0x00,...
...0x00, 0x00, 0x00,
#endif

#if LV_COLOR_DEPTH == 32
/*Pixel format: Fix 0xFF: 8 bit, Red: 8 bit, Green: 8 bit, Blue: 8 bit*/
0x00, 0x00, 0x00,...
...0x00, 0x00, 0xff,
#endif
};

And another small bit of info we will need for later that looks like,

const lv_img_dsc_t bitmap = {
.header.always_zero = 0,
.header.w = 40,
.header.h = 40,
.data_size = 1600 * LV_COLOR_SIZE / 8,
.header.cf = LV_IMG_CF_TRUE_COLOR,
.data = bitmap_map,
};

NOTE: There are some header files at the top, which we can ignore...
===RGB565 image format===

The Pinetime uses a display that uses a 16 bit color space, also known as RGB565.

These 16 bit are assigned to RGB as 5 bits each for Red and Blue and 6 bits for Green, so 5+6+5=16 bits are required, so each pixel's color occupies 2 bytes of data,
and since 216 is equal to 65,536 it allows us to view 65,536 or 65k colors

The way it packs these bits is by converting the bits into 2x 4+4 bit hex-code, so for example,

if the color of a pixel in Binary is '''10110100 01011111''' (this color is approximately Lavender purple)

It is split as '''1011''' & '''0100''' for the first byte and '''0101''' & '''1111''' for the second byte
and so, converting the binary into Hex-code,

the two parts are '''0xB4''' and '''0xF5'''

These two parts in conjunction are used for determining the color of one pixel...

also from the binary, it is observed that,

The bits '''10110''' is used for Red, '''100010''' is used for green, and '''11111''' is used for blue.

===Flipping the bytes===
The LVGL library has a feature that allows you to flip the two bytes of the pixel, so if the two parts were, ...0xB4,0xF5,... ,it will change it to become, ...0xF5,0xB4,...

The reason for this is to allow the use of 8-bit SPI interfaces, but we do not require it, and if set with wrong parameter we could get problems with the color...

To make sure you are ready for the next step, make sure that inside your lvgl configuration file (located at '''src/libs/lv_conf.h''')

this parameter,
'''#define LV_COLOR_16_SWAP 0'''
is set to "0" as seen...

===Creating an Object from the Array===
To include the Icon, first Identify the Array you need to copy to the source (clock.cpp)

The one we require from it is the data below the tag that looks like,
#if LV_COLOR_DEPTH == 16 && LV_COLOR_16_SWAP != 0
/*Pixel format: Red: 5 bit, Green: 6 bit, Blue: 5 bit BUT the 2 bytes are swapped*/
0x00, 0x00, 0x00,...
...0x00, 0x00, 0x00,
#endif

from this copy the Data from the array alone...
I.e this part,
0x00, 0x00, 0x00,...
...0x00, 0x00, 0x00

(Make sure to not include the comma at the end or the #endif as the entire part is going to substitute a new array)

In clock.cpp, just below the header files and the Task creation part (I.e event_handler...),
create a name for the label with,
static lv_img_dsc_t <name>; // remember to replace <name> with the actual name you gave to your image while converting !

then below it create a array to hold the data with,
const uint8_t bitmap_map[] = {<data>}; // paste the array you copied from the conversion file we specified above...

Then inside the Clock::Clock(DisplayApp* app,...){... region,
You need to place a particular set of lines which LVGL uses to define the object declare the array as an Icon/Image, You can place this set of lines above label_time...

<name>.header.always_zero = 0; //Initialization
<name>.header.w = <Hr_length>; // Setting the Width (or) Horizontal length of the image (number of px)
<name>.header.h = <Vr_length>; // Setting the Height (or) vertical length of the image (number of px)
<name>.data_size = <Hr_length> * <Vr_length> * LV_COLOR_SIZE / 8; //Allocation of memory for the image
<name>.header.cf = LV_IMG_CF_TRUE_COLOR; // Sets the color scheme for the image
<name>.data = <name>_map; // Maps the Image data to the Array
lv_obj_t *img_src = lv_img_create(lv_scr_act(), NULL); // Create an image object
lv_img_set_src(img_src, &<name>); // Set the created file as image (<name>)

again, make sure to replace <name> with the name you gave it during conversion!

===RAM vs ROM===

=Using git to work on the firmware=
===Cloning the repository===
===Changing the code to add the image===
===Compiling the firmware===
==Testing the firmware==
===Installing the new firmware===

A holistic guide on how to install different firmware using various hardware programmers is available here: [[Reprogramming the PineTime]]. There's also the possibility of using OTA updating. ''//TODO: add that to the article!''

===Activating the firmware===
===How to troubleshoot===
==Conclusions==
==Next steps==
==More in-depth documentation==
==Thanks for the help==

PineTime Custom Watchface Tutorial

2020-08-17T06:31:46Z

Electr0lyte: /* Flipping the bytes */

=PineTime Custom Watchface Tutorial=

This is a tutorial to help new users create custom watchfaces based on the InfiniTime Firmware for Pinetime made by user JF002, thanks to him for its development...

We will explain some of the things we went through while creating some custom Watchfaces, so consider this as a log of experiments of sorts..

So stay tuned to it as it will be dynamically updated...

==What you need to start==
The entire building process will be done by GitHub, so all you need is a device which can give you a Github Web Client, a PC or tablet to give you enough screen space to review your code and a steady internet connection.

Since the compiling and file management is done by Github online, you have nothing else to worry about other than working with the files that display the watch face.

So with those things settled, let's start with the basics of a watchface.

Please remember that this is a wiki, so you can make an account and help us improve this page.

Please make sure not to unilaterally remove info though, but offer an alternative. If it is indeed a better way, in time your alternative will grow into the main text, and the latter info will be pruned.

==Overview==
The Firmware (also called InfiniTime) we will be working with is made with a programming language named '''C++''':[https://en.wikipedia.org/wiki/C%2B%2B]

Basic knowledge of C/C++ is required to to understand the advanced watch faces as that requires more complex code, but you can still do a some cool things without much knowledge of C++ programming, just some small edits to existing programs.

InfiniTime uses the '''LVGL''':[https://lvgl.io] graphics library to provide users with a simple and clean UI without overpowering the Nordic '''nRF52832''':[http://files.pine64.org/doc/datasheet/pinetime/nRF52832%20product%20brief.pdf] microcontroller which is the brain of the watch.

To get the watchface to work there are these basic steps. We will go over each step separately, so don't be daunted, all will become clear soon.

For now we will, modify the the existing watchface, change the positioning of the text labels, add an icon to an existing watchface, and later on we will do a full watchface.

The main file we need to focus on is the '''clock.cpp''' file, it is what contains most of the data attributed to what we see on the watchface, including The time/day characters, the battery and bluetooth icons, and also pedometer count...

so everything we will be doing in the basic modifications is purely messing with this single file.

==Labels==
===What are labels?===
Labels are considered as "elemental" parts that make up a screen's Text-based UI by the LVGL library...
Each label is also considered as an "object" or "obj" and can be manipulated, by changing the data attributed with the "obj", for example, position, internal data like the strings/text etc.
when can change what the label shows and where it shows it...

===Modifying label data===
let's observe something small like the word "BPM" near the bottom of the watch face...
[[file:PineTimeCustom-1.png|right|200px]]

If we take a look at the source file of the watchface, (a.k.a the clock.cpp file)
we can observe that these particular lines are what attributes to the word "BPM being displayed...
heartbeatBpm = lv_label_create(lv_scr_act(), NULL);
lv_label_set_text(heartbeatBpm, "BPM");

we can modify the text inside the quotes and replace the word 'BPM' between those quotes to something like 'LOVE'
and the result after compiling the firmware again with the changes and flashing it to the watch would be that the text changes on the watch face and displays 'LOVE' inplace of 'BPM'...

If this happened correctly, then you have successfully made a custom new watchface! Now we can do something a bit more complex...

Now take for in instance the days of the week that we have on the bottom line with the date...

they are stored a "C array" which is basically multiple words separated by commas..
the date is in a format of '''<day of the week> <day> <Month> <year>'''

which in the source file is expressed as,
sprintf(dateStr, "%s %d %s %d", DayOfWeekToString(dayOfWeek), day, MonthToString(month), year);
lv_label_set_text(label_date, dateStr);

here,
%s %d %s %d
stores the print format of the variables, and

DayOfWeekToString(dayOfWeek), day, MonthToString(month), year
are the variables themselves...

Now,
if the date was a saturday 11/7/2020, you can observe that the date looks like
SATURDAY 11 JUL 2020
as seen in the above image (the one where we changed BPM to LOVE)

by modifying the format of the variables, we can change how those words are arranged, and add some extra characters if we like...
(there is a catch to the list of characters you can use however, but it will be discussed later...)

For example,

We modifying the format by adding a comma... "," in between the second "%s" and "%d" like this,
"%s %d %s, %d"
and changing that in the line...
sprintf(dateStr, "%s %d %s, %d", DayOfWeekToString(dayOfWeek), day, MonthToString(month), year);

we can make the date become...
SATURDAY 11 JUL, 2020

which means we now were able to modify how the text got display to make it a bit more nice...

but if you haven't noticed, the line containing the date is already full, meaning we will get some problems while displaying the date and causing it to wrap around,
making a single character go to the next line and look more like,

SATURDAY 11 JUL, 202
0

so why don't we shorten the characters present in the date from being "SATURDAY" to simply just "sat." (It will have the small period at the end, and is only 3 characters long)
I will also convert the months of the year from Capital to small letters...

for that look into the part where the days of the week of are stored as text,
and also while looking at it, we can solve another question, why was their two variables in the date format that looked like, DayOfWeekToString(dayOfWeek), and MonthToString(month) ?

It is because the system gives the date/ time as numbers (Monday-1, Tuesday-2 Wednesday-3 for the days, and 1-January, 2-February, 3-March ),
and so a function along with a C array is used to assign these numbers to Days/Months in text form as it is easier to read...

this is the Array containing the day of the week, (as text)
char const *Clock::DaysString[] = {
"",
"MONDAY",
"TUESDAY",
"WEDNESDAY",
"THURSDAY",
"FRIDAY",
"SATURDAY",
"SUNDAY"
};

and this Array stores the months of the year, (as text)
char const *Clock::MonthsString[] = {
"",
"JAN",
"FEB",
"MAR",
"APR",
"MAY",
"JUN",
"JUL",
"AUG",
"SEP",
"OCT",
"NOV",
"DEC"
};

here we can see that the days are stored in a full format as "SUNDAY", "MONDAY", "TUESDAY" etc.
we can change all of them to a shorter format like "sun.", "mon.", "tue.", to make it short and nice...
while doing so, we can even make the months use small letters as said before..

so the source file (clock.cpp) becomes,

(for the days of the week)
char const *Clock::DaysString[] = {
"",
"mon.",
"tue.",
"wed.",
"thu.",
"fri.",
"sat.",
"sun."
};

and

(for the months of the year)
char const *Clock::MonthsString[] = {
"",
"jan",
"feb",
"mar",
"apr",
"may",
"jun",
"jul",
"aug",
"sep",
"oct",
"nov",
"dec"
};

which means now our original date, saturday 11/7/2020 will become...
sat. 11 jul, 2020

you now know how to change the data present in a label object, and the format of it..,

Here is a fun idea you can try: you can even replace the days with whatever thing that tells you (or) reminds you the day of the week
(like the food served in the cafe, Monday/taco, Tuesday/burger, Wednesday/pasta etc.)

NOTE: when making the custom array, don't forget to leave a empty "" as the first element of the array,
This is because the date is given by the system in a natural numbers format (1,2,3...) rather than a zero-starting format (0,1,2,3...), which the C array uses to index...
so the C array indexes the days as ""-0, "Monday"-1, "Tuesday"-2 etc. and the months as ""-0, "January"-1, "February"-2 etc.)

===Label positioning===

The locational placement in LVGL is done on a cartesian plane,
where each object can have dynamic origin placement, and the Y-axis is inverted...
So going down is done with a positive Y-axis value and not negative as the it is by de-facto...

The position of the various objects in clock.cpp are set by the line,
lv_obj_set_pos(<obj>, <new_x>, <new_y>)

and the top left corner is the Cartesian origin, aka coordinates (0,0)

we use another function, that is more advanced that gives the positional alignment based on preset locations...
lv_obj_align(<text/obj>, <image/obj>, <location_parameter>, <new_x>, <new_y>);

the "<image/obj>" data is used for putting text beside other picture icons , and so if using only text based labels, we can substitute it with,
lv_scr_act() (or) NULL

'''<new_x>, <new_y>''' are the cartesian coordinates, '''<location parameter>''' is replaced by '''LV_ALIGN_<preset>''',
there will be a picture showing the presets below, and '''<text/obj>''' is your text label...

here, LV_ALIGN_<preset> sets the cartesian origin...

Label positioning based on alignment is both a simple and complicated thing to understand, so here I have given something you can refer to while modifying the position of the various labels and objects...

you can also refer here for LVGL's documentation of coordinate system https://docs.lvgl.io/v6/en/html/object-types/obj.html#coordinates

It is however recommended that you use the first method to set the location
lv_obj_set_pos(<obj>, <new_x>, <new_y>)
as it is simple and easier for beginners

Here is a small example.

Take the Label that tells the date,
In the source file (clock.cpp) it is this line,
lv_obj_align(label_date, lv_scr_act(), LV_ALIGN_IN_LEFT_MID, 0, 60);
by increasing the Value of the Y coordinate (60) to a higher value, we can bring the position of the Date downwards a bit away from the Time, and toward the Heartbeat count in the bottom row
here I will increase it to 80, so it becomes..
lv_obj_align(label_date, lv_scr_act(), LV_ALIGN_IN_LEFT_MID, 0, 80);

and now we have made some space up top..

now let's try something a bit complex,

Take the position argument for the label that tells you time...
here, in the source file (clock.cpp),
lv_obj_align(label_time, lv_scr_act(), LV_ALIGN_IN_LEFT_MID, 0, 0);

this line determines the position of the Label telling time, as seen in the image...

we modifying this, by changing the origin <preset> parameter (here it is LV_ALIGN_IN_LEFT_MID) to LV_ALIGN_IN_TOP_LEFT

you can alternatively swap the whole line to,
lv_obj_set_pos(label_time, 0, 0);

this makes the Time label/obj. to go to the top left corner...

but I will do something a little extra,
I will modify the label that store the data and Time format,
i.e this line,
sprintf(timeStr, "%c%c:%c%c", hoursChar[0],hoursChar[1],minutesChar[0], minutesChar[1]);

by removing the ":" colon in between the numbers, and replacing it with a Newline symbol "\n"
I change it to become,
sprintf(timeStr, "%c%c\n%c%c", hoursChar[0],hoursChar[1],minutesChar[0], minutesChar[1]);

this gives it a nice wrapped text format in the top corner, and gives us some space to play with in the side, for things like Pictures and icons, which we will do next..

If you have been able to do these things, you now have completed the 2nd part of the tutorial, and now know how to change and modify the position of labels..

==Using icons==
The LVGL library allows for the use of widgets known as "Images", In short it allows you to use small Icons like pictures with a small dedicated function,
However when this was attempted the first time we stumbled on some problems as LVGL v6 (used on the pinetime) is not much documented as the latest release (v7 as of August 2020)
but also the existing code was only documented for C not C++, after some painful attempts we were able to translate it into C++,

To bring images into Clock.cpp
you will need to do the following,

1. Have a small image that cannot exceed a maximum size of 240px x 240px (pinetime max resolution)

2. Use this Image converter (Thanks to LVGL) https://lvgl.io/tools/imageconverter
to convert your image to a C array and having the Color format as "True color" and the output format as "C array"
make sure to use something simple as the name we will be using "bitmap" as the name, but will also be referred as <name> for simplicity

Note: for example we shall use <name> = bitmap, but any simple word can be used, as long as it does not cause problems with system variables

===Image size considerations===
since the image will be written from internal Flash to the RAM, we need to be considerate as to use less RAM as we are capped at 64KB maximum...
for testing we did not exceed more than 30% of the 64KB which is about 19.2KB...

You can calculate the RAM usage of your images with a simple formula..
<picture_X> x <picture_Y> x 2
give you the number of KB the image uses...
where, <picture_X> <picture_Y> are the dimensions of the image horizontally and vertically

for example,
if <picture_X>=80px <picture_Y>=64px
then,
total RAM used = 80 x 60 x 2 = 10.24KB

please use the RAM sparingly, too much and the RAM overflow could cause the MCU to crash... you have been warned !!!

==Preparing the image for inclusion as an icon==

Once you have your obtained your C array from the LVGL converter, you can take a look inside it to see all the different formats of your image,
try using something like Notepad++ or any of your favorite text editors to peek inside of it,

there will be 4 sets of Arrays inside it that look like,

#if LV_COLOR_DEPTH == 1 || LV_COLOR_DEPTH == 8
/*Pixel format: Red: 3 bit, Green: 3 bit, Blue: 2 bit*/
0x00, 0x00, 0x00,...
...0x00, 0x00, 0x00,
#endif

#if LV_COLOR_DEPTH == 16 && LV_COLOR_16_SWAP == 0
/*Pixel format: Red: 5 bit, Green: 6 bit, Blue: 5 bit*/
0x00, 0x00, 0x00,...
...0x00, 0x00, 0x00,
#endif

#if LV_COLOR_DEPTH == 16 && LV_COLOR_16_SWAP != 0
/*Pixel format: Red: 5 bit, Green: 6 bit, Blue: 5 bit BUT the 2 bytes are swapped*/
0x00, 0x00, 0x00,...
...0x00, 0x00, 0x00,
#endif

#if LV_COLOR_DEPTH == 32
/*Pixel format: Fix 0xFF: 8 bit, Red: 8 bit, Green: 8 bit, Blue: 8 bit*/
0x00, 0x00, 0x00,...
...0x00, 0x00, 0xff,
#endif
};

And another small bit of info we will need for later that looks like,

const lv_img_dsc_t bitmap = {
.header.always_zero = 0,
.header.w = 40,
.header.h = 40,
.data_size = 1600 * LV_COLOR_SIZE / 8,
.header.cf = LV_IMG_CF_TRUE_COLOR,
.data = bitmap_map,
};

NOTE: There are some header files at the top, which we can ignore...
===RGB565 image format===

The Pinetime uses a display that uses a 16 bit color space, also known as RGB565.

These 16 bit are assigned to RGB as 5 bits each for Red and Blue and 6 bits for Green, so 5+6+5=16 bits are required, so each pixel's color occupies 2 bytes of data,
and since 216 is equal to 65,536 it allows us to view 65,536 or 65k colors

The way it packs these bits is by converting the bits into 2x 4+4 bit hex-code, so for example,

if the color of a pixel in Binary is '''10110100 01011111''' (this color is approximately Lavender purple)

It is split as '''1011''' & '''0100''' for the first byte and '''0101''' & '''1111''' for the second byte
and so, converting the binary into Hex-code,

the two parts are '''0xB4''' and '''0xF5'''

These two parts in conjunction are used for determining the color of one pixel...

also from the binary, it is observed that,

The bits '''10110''' is used for Red, '''100010''' is used for green, and '''11111''' is used for blue.

===Flipping the bytes===
The LVGL library has a feature that allows you to flip the two bytes of the pixel, so if the two parts were, ...0xB4,0xF5,... ,it will change it to become, ...0xF5,0xB4,...

The reason for this is to allow the use of 8-bit SPI interfaces, but we do not require it, and if set with wrong parameter we could get problems with the color...

To make sure you are ready for the next step, make sure that inside your lvgl configuration file (located at '''src/libs/lv_conf.h''')

this parameter,
'''#define LV_COLOR_16_SWAP 0'''
is set to "0" as seen...

===Creating an Object from the Array===
===RAM vs ROM===

=Using git to work on the firmware=
===Cloning the repository===
===Changing the code to add the image===
===Compiling the firmware===
==Testing the firmware==
===Installing the new firmware===

A holistic guide on how to install different firmware using various hardware programmers is available here: [[Reprogramming the PineTime]]. There's also the possibility of using OTA updating. ''//TODO: add that to the article!''

===Activating the firmware===
===How to troubleshoot===
==Conclusions==
==Next steps==
==More in-depth documentation==
==Thanks for the help==

PineTime Custom Watchface Tutorial

2020-08-17T06:31:12Z

Electr0lyte: /* Flipping the bytes */

=PineTime Custom Watchface Tutorial=

This is a tutorial to help new users create custom watchfaces based on the InfiniTime Firmware for Pinetime made by user JF002, thanks to him for its development...

We will explain some of the things we went through while creating some custom Watchfaces, so consider this as a log of experiments of sorts..

So stay tuned to it as it will be dynamically updated...

==What you need to start==
The entire building process will be done by GitHub, so all you need is a device which can give you a Github Web Client, a PC or tablet to give you enough screen space to review your code and a steady internet connection.

Since the compiling and file management is done by Github online, you have nothing else to worry about other than working with the files that display the watch face.

So with those things settled, let's start with the basics of a watchface.

Please remember that this is a wiki, so you can make an account and help us improve this page.

Please make sure not to unilaterally remove info though, but offer an alternative. If it is indeed a better way, in time your alternative will grow into the main text, and the latter info will be pruned.

==Overview==
The Firmware (also called InfiniTime) we will be working with is made with a programming language named '''C++''':[https://en.wikipedia.org/wiki/C%2B%2B]

Basic knowledge of C/C++ is required to to understand the advanced watch faces as that requires more complex code, but you can still do a some cool things without much knowledge of C++ programming, just some small edits to existing programs.

InfiniTime uses the '''LVGL''':[https://lvgl.io] graphics library to provide users with a simple and clean UI without overpowering the Nordic '''nRF52832''':[http://files.pine64.org/doc/datasheet/pinetime/nRF52832%20product%20brief.pdf] microcontroller which is the brain of the watch.

To get the watchface to work there are these basic steps. We will go over each step separately, so don't be daunted, all will become clear soon.

For now we will, modify the the existing watchface, change the positioning of the text labels, add an icon to an existing watchface, and later on we will do a full watchface.

The main file we need to focus on is the '''clock.cpp''' file, it is what contains most of the data attributed to what we see on the watchface, including The time/day characters, the battery and bluetooth icons, and also pedometer count...

so everything we will be doing in the basic modifications is purely messing with this single file.

==Labels==
===What are labels?===
Labels are considered as "elemental" parts that make up a screen's Text-based UI by the LVGL library...
Each label is also considered as an "object" or "obj" and can be manipulated, by changing the data attributed with the "obj", for example, position, internal data like the strings/text etc.
when can change what the label shows and where it shows it...

===Modifying label data===
let's observe something small like the word "BPM" near the bottom of the watch face...
[[file:PineTimeCustom-1.png|right|200px]]

If we take a look at the source file of the watchface, (a.k.a the clock.cpp file)
we can observe that these particular lines are what attributes to the word "BPM being displayed...
heartbeatBpm = lv_label_create(lv_scr_act(), NULL);
lv_label_set_text(heartbeatBpm, "BPM");

we can modify the text inside the quotes and replace the word 'BPM' between those quotes to something like 'LOVE'
and the result after compiling the firmware again with the changes and flashing it to the watch would be that the text changes on the watch face and displays 'LOVE' inplace of 'BPM'...

If this happened correctly, then you have successfully made a custom new watchface! Now we can do something a bit more complex...

Now take for in instance the days of the week that we have on the bottom line with the date...

they are stored a "C array" which is basically multiple words separated by commas..
the date is in a format of '''<day of the week> <day> <Month> <year>'''

which in the source file is expressed as,
sprintf(dateStr, "%s %d %s %d", DayOfWeekToString(dayOfWeek), day, MonthToString(month), year);
lv_label_set_text(label_date, dateStr);

here,
%s %d %s %d
stores the print format of the variables, and

DayOfWeekToString(dayOfWeek), day, MonthToString(month), year
are the variables themselves...

Now,
if the date was a saturday 11/7/2020, you can observe that the date looks like
SATURDAY 11 JUL 2020
as seen in the above image (the one where we changed BPM to LOVE)

by modifying the format of the variables, we can change how those words are arranged, and add some extra characters if we like...
(there is a catch to the list of characters you can use however, but it will be discussed later...)

For example,

We modifying the format by adding a comma... "," in between the second "%s" and "%d" like this,
"%s %d %s, %d"
and changing that in the line...
sprintf(dateStr, "%s %d %s, %d", DayOfWeekToString(dayOfWeek), day, MonthToString(month), year);

we can make the date become...
SATURDAY 11 JUL, 2020

which means we now were able to modify how the text got display to make it a bit more nice...

but if you haven't noticed, the line containing the date is already full, meaning we will get some problems while displaying the date and causing it to wrap around,
making a single character go to the next line and look more like,

SATURDAY 11 JUL, 202
0

so why don't we shorten the characters present in the date from being "SATURDAY" to simply just "sat." (It will have the small period at the end, and is only 3 characters long)
I will also convert the months of the year from Capital to small letters...

for that look into the part where the days of the week of are stored as text,
and also while looking at it, we can solve another question, why was their two variables in the date format that looked like, DayOfWeekToString(dayOfWeek), and MonthToString(month) ?

It is because the system gives the date/ time as numbers (Monday-1, Tuesday-2 Wednesday-3 for the days, and 1-January, 2-February, 3-March ),
and so a function along with a C array is used to assign these numbers to Days/Months in text form as it is easier to read...

this is the Array containing the day of the week, (as text)
char const *Clock::DaysString[] = {
"",
"MONDAY",
"TUESDAY",
"WEDNESDAY",
"THURSDAY",
"FRIDAY",
"SATURDAY",
"SUNDAY"
};

and this Array stores the months of the year, (as text)
char const *Clock::MonthsString[] = {
"",
"JAN",
"FEB",
"MAR",
"APR",
"MAY",
"JUN",
"JUL",
"AUG",
"SEP",
"OCT",
"NOV",
"DEC"
};

here we can see that the days are stored in a full format as "SUNDAY", "MONDAY", "TUESDAY" etc.
we can change all of them to a shorter format like "sun.", "mon.", "tue.", to make it short and nice...
while doing so, we can even make the months use small letters as said before..

so the source file (clock.cpp) becomes,

(for the days of the week)
char const *Clock::DaysString[] = {
"",
"mon.",
"tue.",
"wed.",
"thu.",
"fri.",
"sat.",
"sun."
};

and

(for the months of the year)
char const *Clock::MonthsString[] = {
"",
"jan",
"feb",
"mar",
"apr",
"may",
"jun",
"jul",
"aug",
"sep",
"oct",
"nov",
"dec"
};

which means now our original date, saturday 11/7/2020 will become...
sat. 11 jul, 2020

you now know how to change the data present in a label object, and the format of it..,

Here is a fun idea you can try: you can even replace the days with whatever thing that tells you (or) reminds you the day of the week
(like the food served in the cafe, Monday/taco, Tuesday/burger, Wednesday/pasta etc.)

NOTE: when making the custom array, don't forget to leave a empty "" as the first element of the array,
This is because the date is given by the system in a natural numbers format (1,2,3...) rather than a zero-starting format (0,1,2,3...), which the C array uses to index...
so the C array indexes the days as ""-0, "Monday"-1, "Tuesday"-2 etc. and the months as ""-0, "January"-1, "February"-2 etc.)

===Label positioning===

The locational placement in LVGL is done on a cartesian plane,
where each object can have dynamic origin placement, and the Y-axis is inverted...
So going down is done with a positive Y-axis value and not negative as the it is by de-facto...

The position of the various objects in clock.cpp are set by the line,
lv_obj_set_pos(<obj>, <new_x>, <new_y>)

and the top left corner is the Cartesian origin, aka coordinates (0,0)

we use another function, that is more advanced that gives the positional alignment based on preset locations...
lv_obj_align(<text/obj>, <image/obj>, <location_parameter>, <new_x>, <new_y>);

the "<image/obj>" data is used for putting text beside other picture icons , and so if using only text based labels, we can substitute it with,
lv_scr_act() (or) NULL

'''<new_x>, <new_y>''' are the cartesian coordinates, '''<location parameter>''' is replaced by '''LV_ALIGN_<preset>''',
there will be a picture showing the presets below, and '''<text/obj>''' is your text label...

here, LV_ALIGN_<preset> sets the cartesian origin...

Label positioning based on alignment is both a simple and complicated thing to understand, so here I have given something you can refer to while modifying the position of the various labels and objects...

you can also refer here for LVGL's documentation of coordinate system https://docs.lvgl.io/v6/en/html/object-types/obj.html#coordinates

It is however recommended that you use the first method to set the location
lv_obj_set_pos(<obj>, <new_x>, <new_y>)
as it is simple and easier for beginners

Here is a small example.

Take the Label that tells the date,
In the source file (clock.cpp) it is this line,
lv_obj_align(label_date, lv_scr_act(), LV_ALIGN_IN_LEFT_MID, 0, 60);
by increasing the Value of the Y coordinate (60) to a higher value, we can bring the position of the Date downwards a bit away from the Time, and toward the Heartbeat count in the bottom row
here I will increase it to 80, so it becomes..
lv_obj_align(label_date, lv_scr_act(), LV_ALIGN_IN_LEFT_MID, 0, 80);

and now we have made some space up top..

now let's try something a bit complex,

Take the position argument for the label that tells you time...
here, in the source file (clock.cpp),
lv_obj_align(label_time, lv_scr_act(), LV_ALIGN_IN_LEFT_MID, 0, 0);

this line determines the position of the Label telling time, as seen in the image...

we modifying this, by changing the origin <preset> parameter (here it is LV_ALIGN_IN_LEFT_MID) to LV_ALIGN_IN_TOP_LEFT

you can alternatively swap the whole line to,
lv_obj_set_pos(label_time, 0, 0);

this makes the Time label/obj. to go to the top left corner...

but I will do something a little extra,
I will modify the label that store the data and Time format,
i.e this line,
sprintf(timeStr, "%c%c:%c%c", hoursChar[0],hoursChar[1],minutesChar[0], minutesChar[1]);

by removing the ":" colon in between the numbers, and replacing it with a Newline symbol "\n"
I change it to become,
sprintf(timeStr, "%c%c\n%c%c", hoursChar[0],hoursChar[1],minutesChar[0], minutesChar[1]);

this gives it a nice wrapped text format in the top corner, and gives us some space to play with in the side, for things like Pictures and icons, which we will do next..

If you have been able to do these things, you now have completed the 2nd part of the tutorial, and now know how to change and modify the position of labels..

==Using icons==
The LVGL library allows for the use of widgets known as "Images", In short it allows you to use small Icons like pictures with a small dedicated function,
However when this was attempted the first time we stumbled on some problems as LVGL v6 (used on the pinetime) is not much documented as the latest release (v7 as of August 2020)
but also the existing code was only documented for C not C++, after some painful attempts we were able to translate it into C++,

To bring images into Clock.cpp
you will need to do the following,

1. Have a small image that cannot exceed a maximum size of 240px x 240px (pinetime max resolution)

2. Use this Image converter (Thanks to LVGL) https://lvgl.io/tools/imageconverter
to convert your image to a C array and having the Color format as "True color" and the output format as "C array"
make sure to use something simple as the name we will be using "bitmap" as the name, but will also be referred as <name> for simplicity

Note: for example we shall use <name> = bitmap, but any simple word can be used, as long as it does not cause problems with system variables

===Image size considerations===
since the image will be written from internal Flash to the RAM, we need to be considerate as to use less RAM as we are capped at 64KB maximum...
for testing we did not exceed more than 30% of the 64KB which is about 19.2KB...

You can calculate the RAM usage of your images with a simple formula..
<picture_X> x <picture_Y> x 2
give you the number of KB the image uses...
where, <picture_X> <picture_Y> are the dimensions of the image horizontally and vertically

for example,
if <picture_X>=80px <picture_Y>=64px
then,
total RAM used = 80 x 60 x 2 = 10.24KB

please use the RAM sparingly, too much and the RAM overflow could cause the MCU to crash... you have been warned !!!

==Preparing the image for inclusion as an icon==

Once you have your obtained your C array from the LVGL converter, you can take a look inside it to see all the different formats of your image,
try using something like Notepad++ or any of your favorite text editors to peek inside of it,

there will be 4 sets of Arrays inside it that look like,

#if LV_COLOR_DEPTH == 1 || LV_COLOR_DEPTH == 8
/*Pixel format: Red: 3 bit, Green: 3 bit, Blue: 2 bit*/
0x00, 0x00, 0x00,...
...0x00, 0x00, 0x00,
#endif

#if LV_COLOR_DEPTH == 16 && LV_COLOR_16_SWAP == 0
/*Pixel format: Red: 5 bit, Green: 6 bit, Blue: 5 bit*/
0x00, 0x00, 0x00,...
...0x00, 0x00, 0x00,
#endif

#if LV_COLOR_DEPTH == 16 && LV_COLOR_16_SWAP != 0
/*Pixel format: Red: 5 bit, Green: 6 bit, Blue: 5 bit BUT the 2 bytes are swapped*/
0x00, 0x00, 0x00,...
...0x00, 0x00, 0x00,
#endif

#if LV_COLOR_DEPTH == 32
/*Pixel format: Fix 0xFF: 8 bit, Red: 8 bit, Green: 8 bit, Blue: 8 bit*/
0x00, 0x00, 0x00,...
...0x00, 0x00, 0xff,
#endif
};

And another small bit of info we will need for later that looks like,

const lv_img_dsc_t bitmap = {
.header.always_zero = 0,
.header.w = 40,
.header.h = 40,
.data_size = 1600 * LV_COLOR_SIZE / 8,
.header.cf = LV_IMG_CF_TRUE_COLOR,
.data = bitmap_map,
};

NOTE: There are some header files at the top, which we can ignore...
===RGB565 image format===

The Pinetime uses a display that uses a 16 bit color space, also known as RGB565.

These 16 bit are assigned to RGB as 5 bits each for Red and Blue and 6 bits for Green, so 5+6+5=16 bits are required, so each pixel's color occupies 2 bytes of data,
and since 216 is equal to 65,536 it allows us to view 65,536 or 65k colors

The way it packs these bits is by converting the bits into 2x 4+4 bit hex-code, so for example,

if the color of a pixel in Binary is '''10110100 01011111''' (this color is approximately Lavender purple)

It is split as '''1011''' & '''0100''' for the first byte and '''0101''' & '''1111''' for the second byte
and so, converting the binary into Hex-code,

the two parts are '''0xB4''' and '''0xF5'''

These two parts in conjunction are used for determining the color of one pixel...

also from the binary, it is observed that,

The bits '''10110''' is used for Red, '''100010''' is used for green, and '''11111''' is used for blue.

===Flipping the bytes===
The LVGL library has a feature that allows you to flip the two bytes of the pixel, so if the two parts were, ...0xB4,0xF5,... ,it will change it to become, ...0xF5,0xB4,...

The reason for this is to allow the use of 8-bit SPI interfaces, but we do not require it, and if set with wrong parameter we could get problems with the color...

To make sure you are ready for the next step, make sure that inside your lvgl configuration file (located at src/libs/lv_conf.h)

this parameter,
#define LV_COLOR_16_SWAP 0
is set to "0" as seen...

===Creating an Object from the Array===
===RAM vs ROM===

=Using git to work on the firmware=
===Cloning the repository===
===Changing the code to add the image===
===Compiling the firmware===
==Testing the firmware==
===Installing the new firmware===

A holistic guide on how to install different firmware using various hardware programmers is available here: [[Reprogramming the PineTime]]. There's also the possibility of using OTA updating. ''//TODO: add that to the article!''

===Activating the firmware===
===How to troubleshoot===
==Conclusions==
==Next steps==
==More in-depth documentation==
==Thanks for the help==

PineTime Custom Watchface Tutorial

2020-08-17T06:04:48Z

Electr0lyte: /* Preparing the image for inclusion as an icon */

=PineTime Custom Watchface Tutorial=

This is a tutorial to help new users create custom watchfaces based on the InfiniTime Firmware for Pinetime made by user JF002, thanks to him for its development...

We will explain some of the things we went through while creating some custom Watchfaces, so consider this as a log of experiments of sorts..

So stay tuned to it as it will be dynamically updated...

==What you need to start==
The entire building process will be done by GitHub, so all you need is a device which can give you a Github Web Client, a PC or tablet to give you enough screen space to review your code and a steady internet connection.

Since the compiling and file management is done by Github online, you have nothing else to worry about other than working with the files that display the watch face.

So with those things settled, let's start with the basics of a watchface.

Please remember that this is a wiki, so you can make an account and help us improve this page.

Please make sure not to unilaterally remove info though, but offer an alternative. If it is indeed a better way, in time your alternative will grow into the main text, and the latter info will be pruned.

==Overview==
The Firmware (also called InfiniTime) we will be working with is made with a programming language named '''C++''':[https://en.wikipedia.org/wiki/C%2B%2B]

Basic knowledge of C/C++ is required to to understand the advanced watch faces as that requires more complex code, but you can still do a some cool things without much knowledge of C++ programming, just some small edits to existing programs.

InfiniTime uses the '''LVGL''':[https://lvgl.io] graphics library to provide users with a simple and clean UI without overpowering the Nordic '''nRF52832''':[http://files.pine64.org/doc/datasheet/pinetime/nRF52832%20product%20brief.pdf] microcontroller which is the brain of the watch.

To get the watchface to work there are these basic steps. We will go over each step separately, so don't be daunted, all will become clear soon.

For now we will, modify the the existing watchface, change the positioning of the text labels, add an icon to an existing watchface, and later on we will do a full watchface.

The main file we need to focus on is the '''clock.cpp''' file, it is what contains most of the data attributed to what we see on the watchface, including The time/day characters, the battery and bluetooth icons, and also pedometer count...

so everything we will be doing in the basic modifications is purely messing with this single file.

==Labels==
===What are labels?===
Labels are considered as "elemental" parts that make up a screen's Text-based UI by the LVGL library...
Each label is also considered as an "object" or "obj" and can be manipulated, by changing the data attributed with the "obj", for example, position, internal data like the strings/text etc.
when can change what the label shows and where it shows it...

===Modifying label data===
let's observe something small like the word "BPM" near the bottom of the watch face...
[[file:PineTimeCustom-1.png|right|200px]]

If we take a look at the source file of the watchface, (a.k.a the clock.cpp file)
we can observe that these particular lines are what attributes to the word "BPM being displayed...
heartbeatBpm = lv_label_create(lv_scr_act(), NULL);
lv_label_set_text(heartbeatBpm, "BPM");

we can modify the text inside the quotes and replace the word 'BPM' between those quotes to something like 'LOVE'
and the result after compiling the firmware again with the changes and flashing it to the watch would be that the text changes on the watch face and displays 'LOVE' inplace of 'BPM'...

If this happened correctly, then you have successfully made a custom new watchface! Now we can do something a bit more complex...

Now take for in instance the days of the week that we have on the bottom line with the date...

they are stored a "C array" which is basically multiple words separated by commas..
the date is in a format of '''<day of the week> <day> <Month> <year>'''

which in the source file is expressed as,
sprintf(dateStr, "%s %d %s %d", DayOfWeekToString(dayOfWeek), day, MonthToString(month), year);
lv_label_set_text(label_date, dateStr);

here,
%s %d %s %d
stores the print format of the variables, and

DayOfWeekToString(dayOfWeek), day, MonthToString(month), year
are the variables themselves...

Now,
if the date was a saturday 11/7/2020, you can observe that the date looks like
SATURDAY 11 JUL 2020
as seen in the above image (the one where we changed BPM to LOVE)

by modifying the format of the variables, we can change how those words are arranged, and add some extra characters if we like...
(there is a catch to the list of characters you can use however, but it will be discussed later...)

For example,

We modifying the format by adding a comma... "," in between the second "%s" and "%d" like this,
"%s %d %s, %d"
and changing that in the line...
sprintf(dateStr, "%s %d %s, %d", DayOfWeekToString(dayOfWeek), day, MonthToString(month), year);

we can make the date become...
SATURDAY 11 JUL, 2020

which means we now were able to modify how the text got display to make it a bit more nice...

but if you haven't noticed, the line containing the date is already full, meaning we will get some problems while displaying the date and causing it to wrap around,
making a single character go to the next line and look more like,

SATURDAY 11 JUL, 202
0

so why don't we shorten the characters present in the date from being "SATURDAY" to simply just "sat." (It will have the small period at the end, and is only 3 characters long)
I will also convert the months of the year from Capital to small letters...

for that look into the part where the days of the week of are stored as text,
and also while looking at it, we can solve another question, why was their two variables in the date format that looked like, DayOfWeekToString(dayOfWeek), and MonthToString(month) ?

It is because the system gives the date/ time as numbers (Monday-1, Tuesday-2 Wednesday-3 for the days, and 1-January, 2-February, 3-March ),
and so a function along with a C array is used to assign these numbers to Days/Months in text form as it is easier to read...

this is the Array containing the day of the week, (as text)
char const *Clock::DaysString[] = {
"",
"MONDAY",
"TUESDAY",
"WEDNESDAY",
"THURSDAY",
"FRIDAY",
"SATURDAY",
"SUNDAY"
};

and this Array stores the months of the year, (as text)
char const *Clock::MonthsString[] = {
"",
"JAN",
"FEB",
"MAR",
"APR",
"MAY",
"JUN",
"JUL",
"AUG",
"SEP",
"OCT",
"NOV",
"DEC"
};

here we can see that the days are stored in a full format as "SUNDAY", "MONDAY", "TUESDAY" etc.
we can change all of them to a shorter format like "sun.", "mon.", "tue.", to make it short and nice...
while doing so, we can even make the months use small letters as said before..

so the source file (clock.cpp) becomes,

(for the days of the week)
char const *Clock::DaysString[] = {
"",
"mon.",
"tue.",
"wed.",
"thu.",
"fri.",
"sat.",
"sun."
};

and

(for the months of the year)
char const *Clock::MonthsString[] = {
"",
"jan",
"feb",
"mar",
"apr",
"may",
"jun",
"jul",
"aug",
"sep",
"oct",
"nov",
"dec"
};

which means now our original date, saturday 11/7/2020 will become...
sat. 11 jul, 2020

you now know how to change the data present in a label object, and the format of it..,

Here is a fun idea you can try: you can even replace the days with whatever thing that tells you (or) reminds you the day of the week
(like the food served in the cafe, Monday/taco, Tuesday/burger, Wednesday/pasta etc.)

NOTE: when making the custom array, don't forget to leave a empty "" as the first element of the array,
This is because the date is given by the system in a natural numbers format (1,2,3...) rather than a zero-starting format (0,1,2,3...), which the C array uses to index...
so the C array indexes the days as ""-0, "Monday"-1, "Tuesday"-2 etc. and the months as ""-0, "January"-1, "February"-2 etc.)

===Label positioning===

The locational placement in LVGL is done on a cartesian plane,
where each object can have dynamic origin placement, and the Y-axis is inverted...
So going down is done with a positive Y-axis value and not negative as the it is by de-facto...

The position of the various objects in clock.cpp are set by the line,
lv_obj_set_pos(<obj>, <new_x>, <new_y>)

and the top left corner is the Cartesian origin, aka coordinates (0,0)

we use another function, that is more advanced that gives the positional alignment based on preset locations...
lv_obj_align(<text/obj>, <image/obj>, <location_parameter>, <new_x>, <new_y>);

the "<image/obj>" data is used for putting text beside other picture icons , and so if using only text based labels, we can substitute it with,
lv_scr_act() (or) NULL

'''<new_x>, <new_y>''' are the cartesian coordinates, '''<location parameter>''' is replaced by '''LV_ALIGN_<preset>''',
there will be a picture showing the presets below, and '''<text/obj>''' is your text label...

here, LV_ALIGN_<preset> sets the cartesian origin...

Label positioning based on alignment is both a simple and complicated thing to understand, so here I have given something you can refer to while modifying the position of the various labels and objects...

you can also refer here for LVGL's documentation of coordinate system https://docs.lvgl.io/v6/en/html/object-types/obj.html#coordinates

It is however recommended that you use the first method to set the location
lv_obj_set_pos(<obj>, <new_x>, <new_y>)
as it is simple and easier for beginners

Here is a small example.

Take the Label that tells the date,
In the source file (clock.cpp) it is this line,
lv_obj_align(label_date, lv_scr_act(), LV_ALIGN_IN_LEFT_MID, 0, 60);
by increasing the Value of the Y coordinate (60) to a higher value, we can bring the position of the Date downwards a bit away from the Time, and toward the Heartbeat count in the bottom row
here I will increase it to 80, so it becomes..
lv_obj_align(label_date, lv_scr_act(), LV_ALIGN_IN_LEFT_MID, 0, 80);

and now we have made some space up top..

now let's try something a bit complex,

Take the position argument for the label that tells you time...
here, in the source file (clock.cpp),
lv_obj_align(label_time, lv_scr_act(), LV_ALIGN_IN_LEFT_MID, 0, 0);

this line determines the position of the Label telling time, as seen in the image...

we modifying this, by changing the origin <preset> parameter (here it is LV_ALIGN_IN_LEFT_MID) to LV_ALIGN_IN_TOP_LEFT

you can alternatively swap the whole line to,
lv_obj_set_pos(label_time, 0, 0);

this makes the Time label/obj. to go to the top left corner...

but I will do something a little extra,
I will modify the label that store the data and Time format,
i.e this line,
sprintf(timeStr, "%c%c:%c%c", hoursChar[0],hoursChar[1],minutesChar[0], minutesChar[1]);

by removing the ":" colon in between the numbers, and replacing it with a Newline symbol "\n"
I change it to become,
sprintf(timeStr, "%c%c\n%c%c", hoursChar[0],hoursChar[1],minutesChar[0], minutesChar[1]);

this gives it a nice wrapped text format in the top corner, and gives us some space to play with in the side, for things like Pictures and icons, which we will do next..

If you have been able to do these things, you now have completed the 2nd part of the tutorial, and now know how to change and modify the position of labels..

==Using icons==
The LVGL library allows for the use of widgets known as "Images", In short it allows you to use small Icons like pictures with a small dedicated function,
However when this was attempted the first time we stumbled on some problems as LVGL v6 (used on the pinetime) is not much documented as the latest release (v7 as of August 2020)
but also the existing code was only documented for C not C++, after some painful attempts we were able to translate it into C++,

To bring images into Clock.cpp
you will need to do the following,

1. Have a small image that cannot exceed a maximum size of 240px x 240px (pinetime max resolution)

2. Use this Image converter (Thanks to LVGL) https://lvgl.io/tools/imageconverter
to convert your image to a C array and having the Color format as "True color" and the output format as "C array"
make sure to use something simple as the name we will be using "bitmap" as the name, but will also be referred as <name> for simplicity

Note: for example we shall use <name> = bitmap, but any simple word can be used, as long as it does not cause problems with system variables

===Image size considerations===
since the image will be written from internal Flash to the RAM, we need to be considerate as to use less RAM as we are capped at 64KB maximum...
for testing we did not exceed more than 30% of the 64KB which is about 19.2KB...

You can calculate the RAM usage of your images with a simple formula..
<picture_X> x <picture_Y> x 2
give you the number of KB the image uses...
where, <picture_X> <picture_Y> are the dimensions of the image horizontally and vertically

for example,
if <picture_X>=80px <picture_Y>=64px
then,
total RAM used = 80 x 60 x 2 = 10.24KB

please use the RAM sparingly, too much and the RAM overflow could cause the MCU to crash... you have been warned !!!

==Preparing the image for inclusion as an icon==

Once you have your obtained your C array from the LVGL converter, you can take a look inside it to see all the different formats of your image,
try using something like Notepad++ or any of your favorite text editors to peek inside of it,

there will be 4 sets of Arrays inside it that look like,

#if LV_COLOR_DEPTH == 1 || LV_COLOR_DEPTH == 8
/*Pixel format: Red: 3 bit, Green: 3 bit, Blue: 2 bit*/
0x00, 0x00, 0x00,...
...0x00, 0x00, 0x00,
#endif

#if LV_COLOR_DEPTH == 16 && LV_COLOR_16_SWAP == 0
/*Pixel format: Red: 5 bit, Green: 6 bit, Blue: 5 bit*/
0x00, 0x00, 0x00,...
...0x00, 0x00, 0x00,
#endif

#if LV_COLOR_DEPTH == 16 && LV_COLOR_16_SWAP != 0
/*Pixel format: Red: 5 bit, Green: 6 bit, Blue: 5 bit BUT the 2 bytes are swapped*/
0x00, 0x00, 0x00,...
...0x00, 0x00, 0x00,
#endif

#if LV_COLOR_DEPTH == 32
/*Pixel format: Fix 0xFF: 8 bit, Red: 8 bit, Green: 8 bit, Blue: 8 bit*/
0x00, 0x00, 0x00,...
...0x00, 0x00, 0xff,
#endif
};

And another small bit of info we will need for later that looks like,

const lv_img_dsc_t bitmap = {
.header.always_zero = 0,
.header.w = 40,
.header.h = 40,
.data_size = 1600 * LV_COLOR_SIZE / 8,
.header.cf = LV_IMG_CF_TRUE_COLOR,
.data = bitmap_map,
};

NOTE: There are some header files at the top, which we can ignore...
===RGB565 image format===

The Pinetime uses a display that uses a 16 bit color space, also known as RGB565.

These 16 bit are assigned to RGB as 5 bits each for Red and Blue and 6 bits for Green, so 5+6+5=16 bits are required, so each pixel's color occupies 2 bytes of data,
and since 216 is equal to 65,536 it allows us to view 65,536 or 65k colors

The way it packs these bits is by converting the bits into 2x 4+4 bit hex-code, so for example,

if the color of a pixel in Binary is '''10110100 01011111''' (this color is approximately Lavender purple)

It is split as '''1011''' & '''0100''' for the first byte and '''0101''' & '''1111''' for the second byte
and so, converting the binary into Hex-code,

the two parts are '''0xB4''' and '''0xF5'''

These two parts in conjunction are used for determining the color of one pixel...

also from the binary, it is observed that,

The bits '''10110''' is used for Red, '''100010''' is used for green, and '''11111''' is used for blue.

===Flipping the bytes===
===Creating an Object from the Array===
===RAM vs ROM===

=Using git to work on the firmware=
===Cloning the repository===
===Changing the code to add the image===
===Compiling the firmware===
==Testing the firmware==
===Installing the new firmware===

A holistic guide on how to install different firmware using various hardware programmers is available here: [[Reprogramming the PineTime]]. There's also the possibility of using OTA updating. ''//TODO: add that to the article!''

===Activating the firmware===
===How to troubleshoot===
==Conclusions==
==Next steps==
==More in-depth documentation==
==Thanks for the help==

PineTime Custom Watchface Tutorial

2020-08-15T15:36:08Z

Electr0lyte: /* Using icons */

User:Electr0lyte

2020-08-15T15:07:29Z

Electr0lyte: Basic Info

Computer and Embedded electronics Enthusiast (⌐■_■)

Follow me on twitter, https://twitter.com/SravanSenthiln1

PineTime Custom Watchface Tutorial

2020-08-14T15:35:14Z

Electr0lyte: /* Label positioning */

PineTime Custom Watchface Tutorial

2020-08-14T15:34:09Z

Electr0lyte: /* Label positioning */

PineTime Custom Watchface Tutorial

2020-08-14T15:30:54Z

Electr0lyte: /* Label positioning */

PineTime Custom Watchface Tutorial

2020-08-14T15:29:22Z

Electr0lyte: /* Label positioning */

PineTime Custom Watchface Tutorial

2020-08-14T15:28:26Z

Electr0lyte: /* Modifying label data */

PineTime Custom Watchface Tutorial

2020-08-14T15:11:34Z

Electr0lyte: /* Label positioning */

PineTime Custom Watchface Tutorial

2020-08-14T14:37:45Z

Electr0lyte: /* Label positioning */

PineTime Custom Watchface Tutorial

2020-08-14T06:53:04Z

Electr0lyte: /* Label positioning */

PineTime Custom Watchface Tutorial

2020-08-13T09:27:53Z

Electr0lyte: /* Modifying label data */ (completed)

PineTime Custom Watchface Tutorial

2020-08-13T07:59:29Z

Electr0lyte: label modification

PineTime Custom Watchface Tutorial

2020-08-12T09:48:26Z

Electr0lyte: modification of label data (not finished)

PineTime Custom Watchface Tutorial

2020-08-12T06:15:11Z

Electr0lyte: /* Modifying label data */

PineTime Custom Watchface Tutorial

2020-08-12T06:06:27Z

Electr0lyte: /* Modifying label data */

PineTime Custom Watchface Tutorial

2020-08-12T05:54:06Z

Electr0lyte: /* Overview */

PineTime Custom Watchface Tutorial

2020-08-12T05:28:48Z

Electr0lyte: adding image

PineTime Custom Watchface Tutorial

2020-08-12T05:27:57Z

Electr0lyte: adding image

PineTime Custom Watchface Tutorial

2020-08-12T05:26:50Z

Electr0lyte: adding image

PineTime Custom Watchface Tutorial

2020-08-12T05:21:47Z

Electr0lyte: /* Modifying label data */

File:PineTimeCustom-1.png

2020-08-12T05:17:02Z

Electr0lyte: picture (1) in the pinetime custom tutorial

== Summary ==
picture (1) in the pinetime custom tutorial
== Licensing ==
{{subst:Unknown_copyright}}

PineTime Custom Watchface Tutorial

2020-08-12T05:14:01Z

Electr0lyte: /* Modifying label data */

PineTime Custom Watchface Tutorial

2020-08-12T05:09:37Z

Electr0lyte: /* What are labels? */

PineTime Custom Watchface Tutorial

2020-08-10T09:19:55Z

Electr0lyte:

PineTime Custom Watchface Tutorial

2020-08-10T09:17:10Z

Electr0lyte:

PineTime Custom Watchface Tutorial

2020-08-10T09:15:40Z

Electr0lyte:

PineTime Custom Watchface Tutorial

2020-08-10T09:14:57Z

Electr0lyte:

PineTime Custom Watchface Tutorial

2020-08-10T06:34:27Z

Electr0lyte:

Hi, this is a simple tutorial to help new users create custom watchfaces based on the InfiniTime Firmware for Pinetime made by user JF002, thanks to him for its development..

I will explain some of the things I went through while creating some custom Watchfaces, so consider this as a log of sorts..

So stay tuned to it as I keep updating it...

==What you need to start:==

The entire building process will be done on the cloud, so all you need is a device which can give you a Github Web Client, and a proper internet connection...

Try using a device like a PC or tablet to give you enough screen space to review your code...

since the compiling and file management is done in Github itself, you have nothing else to worry about other than working with the file that displays the watch face

So with those things in mind, let's start with the basics of the watchface.

==The basics==

The Firmware (also called InfiniTime) we will be working with is comprised of code made with the common programming language known as '''C++''':[https://en.wikipedia.org/wiki/C%2B%2B]

basic knowledge of C/C++ is required to to understand the advanced watch faces where we will work with more complex code...

but you can still do a few things without the knowledge of C++ programming, and just your brain...

The firmware uses the '''LVGL''':[https://lvgl.io] graphics library to provide users with a simple and clean UI without overpowering the Nordic '''nRF52832''':[http://files.pine64.org/doc/datasheet/pinetime/nRF52832%20product%20brief.pdf] microcontroller which is the brains of the operation inside the watch...

PineTime Custom Watchface Tutorial

2020-08-10T06:19:31Z

Electr0lyte:

PineTime Custom Watchface Tutorial

2020-08-10T06:19:11Z

Electr0lyte:

PineTime Custom Watchface Tutorial

2020-08-10T06:12:47Z

Electr0lyte:

PineTime Custom Watchface Tutorial

2020-08-10T06:04:44Z

Electr0lyte: