[[Category:PineTime]]

Infinitime-Weather

2023-05-19T19:55:29Z

Kieranc: Removed redirect to User:Kieranc/Infinitime-Weather

User:Kieranc/Infinitime-Weather

2023-05-01T12:39:33Z

Kieranc: Initial draft of info about weather data on Infinitime

==Infinitime Weather==

Infinitime features a weather subsystem which stores weather data on the watch in a timeline which can be queried by apps or watchfaces. It can store many different types of data ([https://github.com/InfiniTimeOrg/InfiniTime/blob/main/src/components/ble/weather/WeatherData.h see here]) and each entry includes a timestamp and an expiry time. When entries expire they are removed from the timeline automatically.

===Sending weather data to the watch===

Weather data must be sent to the watch via a companion app, currently Gadgetbridge and ITD have this functionality implemented.
ITD is the easiest option as the feature simply needs enabling in the config file with a location specified. It uses MET.no data and provides one hour of data at a time.
Gadgetbridge is slightly more difficult to set up as it requires a separate app to fetch the weather data. Details are available on the [https://codeberg.org/Freeyourgadget/Gadgetbridge/wiki/Weather Gadgetbridge wiki]. There is currently (May 2023) a bug in the Pinetime implementation within Gadgetbridge which sets the expiry time to 5 minutes instead of the desired 6 hours, it should be resolved in the next available Gadgetbridge release.

===Displaying weather data===
Currently there are 2 ways to display weather data on the watch, a debug app which is disabled by default, and the PineTimeStyle watchface.
<Add details for enabling debug app>
PineTimeStyle can display basic weather data in the sidebar when the option is enabled, see details here [[PineTimeStyle]]

PineTimeStyle

2022-10-18T19:10:51Z

Kieranc: /* Customisation */

=PineTimeStyle Watchface=
PineTimeStyle is a watchface created for Infinitime and has been included since version 1.3 of Infinitime.

It is based on [https://www.dantilden.com/projects/timestyle/ TimeStyle for Pebble by Dan Tilden] with permission.

[[File:PineTimeStyle-Watchface.png|PineTimeStyle Watchface]]

==Layout==
The time is displayed on the left in either 12 or 24h format depending on the system setting. An indicator will appear in the bottom left corner if 12h is selected.

In the sidebar on the right there is a battery icon which displays the current charge level, and is replaced by a plug icon when charging. Below it is a bluetooth icon which appears only when bluetooth is connected, and a lower case '''i''' which indicates unread notifications are available, generally only if notifications are disabled via the quick settings screen.

The current date is displayed in the middle, and at the bottom there is a small gauge which displays the step count, the needle will rotate in a clockwise direction as the step count increases. The gauge scales automatically based on the configured step goal, and the outside of the gauge will turn white when the step goal is reached.

=Customisation=
Since version 1.4 of Infinitime, a color picker is available for PineTimeStyle. As of version 1.11, an addition page of customisation has been added which allows the user to customise the sidebar. These settings can be accessed by long pressing on the watchface which will display two buttons, one with a palette icon to access the color settings, one with a cog icon for the sidebar options.

[[File:PineTimeStyle-Settings-1.11.png|PineTimeStyle Settings Button]]

==The color picker==
[[File:PineTimeStyle-Settings.png|PineTimeStyle Color Settings Interface]]

There are 3 pairs of buttons with left and right arrows which scroll through 17 standard colors. The top pair changes the time text color, middle for the sidebar color and bottom for the time background color.

There is also a 'Rnd' button which randomises all colors, a 'Rst' button which resets the colors to standard teal and black, and a cross which closes the settings interface. It can also be closed using the physical button.

==The sidebar settings==
[[File:PineTimeStyle-SidebarSettings.png|PineTimeStyle Sidebar Settings]]

The sidebar settings currently only has one option, for the step gauge style. By pressing the 'Steps style' button you can toggle between 3 options, the original full gauge, a half size gauge plus seconds display, or a numerical step count display. The image above shows the half gauge plus seconds. Further options will be added in the future!

[[Category:PineTime]]

File:PineTimeStyle-SidebarSettings.png

2022-10-18T19:06:29Z

Kieranc:

File:PineTimeStyle-Settings-1.11.png

2022-10-18T19:04:21Z

Kieranc:

PineTimeStyle

2022-06-18T11:56:39Z

Kieranc: /* Layout */

=PineTimeStyle Watchface=
PineTimeStyle is a watchface created for Infinitime and has been included since version 1.3 of Infinitime.

It is based on [https://www.dantilden.com/projects/timestyle/ TimeStyle for Pebble by Dan Tilden] with permission.

[[File:PineTimeStyle-Watchface.png|PineTimeStyle Watchface]]

==Layout==
The time is displayed on the left in either 12 or 24h format depending on the system setting. An indicator will appear in the bottom left corner if 12h is selected.

In the sidebar on the right there is a battery icon which displays the current charge level, and is replaced by a plug icon when charging. Below it is a bluetooth icon which appears only when bluetooth is connected, and a lower case '''i''' which indicates unread notifications are available, generally only if notifications are disabled via the quick settings screen.

The current date is displayed in the middle, and at the bottom there is a small gauge which displays the step count, the needle will rotate in a clockwise direction as the step count increases. The gauge scales automatically based on the configured step goal, and the outside of the gauge will turn white when the step goal is reached.

==Customisation==
Since version 1.4 of Infinitime, a color picker is available for PineTimeStyle. It can be accessed by long pressing on the watchface which will display a button with a cog icon - if you press this button, the settings will open.

[[File:PineTimeStyle-SettingsButton.png|PineTimeStyle Settings Button]] [[File:PineTimeStyle-Settings.png|PineTimeStyle Settings Interface]]

There are 3 pairs of buttons with left and right arrows which scroll through 17 standard colors. The top pair changes the time text color, middle for the sidebar color and bottom for the time background color.

There is also a 'Rnd' button which randomises all colors, a 'Rst' button which resets the colors to standard teal and black, and a cross which closes the settings interface. It can also be closed using the physical button.

[[Category:PineTime]]

PineTimeStyle

2022-06-18T11:55:27Z

Kieranc: /* Layout */

=PineTimeStyle Watchface=
PineTimeStyle is a watchface created for Infinitime and has been included since version 1.3 of Infinitime.

It is based on [https://www.dantilden.com/projects/timestyle/ TimeStyle for Pebble by Dan Tilden] with permission.

[[File:PineTimeStyle-Watchface.png|PineTimeStyle Watchface]]

==Layout==
The time is displayed on the left in either 12 or 24h format depending on the system setting. An indicator will appear in the bottom left corner if 12h is selected.

In the sidebar on the right there is a battery icon which displays the current charge level, and is replaced by a plug icon when charging. Below it is a bluetooth icon which appears only when bluetooth is connected, and a lower case '''i''' which indicates unread notifications are available, generally only if notifications are disabled via the quick settings screen.

The current date is displayed in the middle, and at the bottom there is a small gauge which displays the step count. The gauge scales automatically based on the configured step goal, and the outside of the gauge will turn white when the step goal is reached.

==Customisation==
Since version 1.4 of Infinitime, a color picker is available for PineTimeStyle. It can be accessed by long pressing on the watchface which will display a button with a cog icon - if you press this button, the settings will open.

[[File:PineTimeStyle-SettingsButton.png|PineTimeStyle Settings Button]] [[File:PineTimeStyle-Settings.png|PineTimeStyle Settings Interface]]

There are 3 pairs of buttons with left and right arrows which scroll through 17 standard colors. The top pair changes the time text color, middle for the sidebar color and bottom for the time background color.

There is also a 'Rnd' button which randomises all colors, a 'Rst' button which resets the colors to standard teal and black, and a cross which closes the settings interface. It can also be closed using the physical button.

[[Category:PineTime]]

PineTimeStyle

2022-06-18T11:53:46Z

Kieranc: Update documentation and images for new version

=PineTimeStyle Watchface=
PineTimeStyle is a watchface created for Infinitime and has been included since version 1.3 of Infinitime.

It is based on [https://www.dantilden.com/projects/timestyle/ TimeStyle for Pebble by Dan Tilden] with permission.

[[File:PineTimeStyle-Watchface.png|PineTimeStyle Watchface]]

==Layout==
The time is displayed on the left in either 12 or 24h format depending on the system setting. An indicator will appear in the bottom left corner if 12h is selected.

In the sidebar on the right there is a battery icon which displays the current charge level, and is replaced by a plug icon when charging. Below it is a bluetooth icon which appears only when bluetooth is connected, and a lower case '''i''' which indicates unread notifications are available. The notification icon only appears when notifications are disabled via the quick settings screen.

The current date is displayed in the middle, and at the bottom there is a small gauge which displays the step count. The gauge scales automatically based on the configured step goal, and the outside of the gauge will turn white when the step goal is reached.

==Customisation==
Since version 1.4 of Infinitime, a color picker is available for PineTimeStyle. It can be accessed by long pressing on the watchface which will display a button with a cog icon - if you press this button, the settings will open.

[[File:PineTimeStyle-SettingsButton.png|PineTimeStyle Settings Button]] [[File:PineTimeStyle-Settings.png|PineTimeStyle Settings Interface]]

There are 3 pairs of buttons with left and right arrows which scroll through 17 standard colors. The top pair changes the time text color, middle for the sidebar color and bottom for the time background color.

There is also a 'Rnd' button which randomises all colors, a 'Rst' button which resets the colors to standard teal and black, and a cross which closes the settings interface. It can also be closed using the physical button.

[[Category:PineTime]]

File:PineTimeStyle-Settings.png

2022-06-18T11:50:28Z

Kieranc:

File:PineTimeStyle-SettingsButton.png

2022-06-18T11:49:46Z

Kieranc:

File:PineTimeStyle-Watchface.png

2022-06-18T11:48:19Z

Kieranc:

Switching your PineTime between InfiniTime and Wasp-os

2022-02-27T13:50:44Z

Kieranc: fix typo

[[File:Flash-reloader-mcuboot.jpg|600px|thumb|right|Flashing <code>reloader-mcuboot.zip</code>]]
[[File:Flash-micropython.jpg|400px|thumb|right|Flashing <code>micropython.zip</code>]]
== Introduction ==
Both Infinitime and Wasp-os are very cool OS'es for the [[PineTime]] and many people will want to try both. This is possible, even with a sealed device!

Both devices use the same Nordic (legacy) DFU protocol for updating firmware over the air. But the BLE stack and the bootloaders for both are different. That's why we need to use the [https://github.com/daniel-thompson/wasp-reloader reloader]. However, instructions you find elsewhere (including [https://www.youtube.com/watch?v=lPasAt1LJmo Daniel Thompsons video]) are somewhat outdated.

Flashing can be done with any of
* nRF Connect for Mobile ([https://play.google.com/store/apps/details?id=no.nordicsemi.android.mcp Android], [https://apps.apple.com/us/app/nrf-connect-bluetooth-app/id1054362403 iOS])
* [https://www.gadgetbridge.org Gadgetbridge] (Android >= 4.4)
* [https://github.com/piggz/harbour-amazfish Amazfish] (SailfishOS and Linux)
* [https://github.com/alexr4535/siglo Siglo] (Linux desktop and Pinephone) (Use the 'Manual OTA File' option)
* [https://github.com/ZephyrLabs/PinetimeFlasher PinetimeFlasher] (Windows)
* ota-dfu-python (Linux CLI) which is included in sources of both Infinitime and Wasp-os
** <code>InfiniTime/bootloader/ota-dfu-python/dfu.py</code>
** <code>wasp-os/tools/ota-dfu-python/dfu.py</code>

This guide has been last updated for Infinitime 1.1.0 and Wasp-os 0.4.1

== InfiniTime => Wasp-os ==

All the zips you need can be found from the [https://wasp-os.readthedocs.io/en/latest/install.html#binary-downloads wasp-os installation guide].

* Make sure the watch is running Infinitime and can be found by your companion device (PC, phone, etc).
* First we need to flash the reloader, with the wasp-os bootloader as payload. To do this, flash: <code>wasp-os-0.4/build-pinetime/reloader-mcuboot.zip</code>
* After flashing, it will boot using the Infinitime bootloader (green large pine cone), then it'll hang for a few seconds, then it'll show the reloader animation (blue smaller pine cone), and then it'll boot the wasp-os bootloader.
* Make sure the watch is on the screen with the pine cone and arrow. If it is in a bootloop instead, then reboot the watch by holding the button until the arrow appears.
* Now you can flash micropython with wasp-os: <code>wasp-os-0.4/build-pinetime/micropython.zip</code>
* Wasp-os should now boot. Enjoy!

== Wasp-os => InfiniTime ==
[[File:Flash-reloader-infinitime-recovery.jpg|500px|thumb|right|Flashing <code>reloader-infinitime-recovery-0.14.1.zip.zip</code>]]
[[File:Flash-infinitime.jpg|600px|thumb|right|Flashing <code>pinetime-mcuboot-app-dfu-1.1.0.zip.zip</code>]]

The <code>reloader-factory.zip</code> was broken in the original wasp-os 0.4 but was fixed in wasp-os 0.4.1. However the Infinitime binaries are outdated the 0.4 release and I do not recommend flashing these. Older InfiniTime versions have flaky BLE which makes upgrading from there very unreliable.

You can get newer binaries from the wasp-os projects CI system (see the [https://wasp-os.readthedocs.io/en/latest/install.html#binary-downloads wasp-os installation guide]) or alternatively, I made my own containing just the [https://github.com/JF002/InfiniTime/releases/tag/0.14.1 InfiniTime 0.14.1] [https://github.com/JF002/pinetime-mcuboot-bootloader/blob/develop/README.md#recovery-firmware recovery firmware]. This allows you to flash any future release of InfiniTime without having to find a new reloader zip. Get the [https://github.com/Peetz0r/wasp-reloader/releases/tag/infinitime-0.14.1-recovery reloader zip here] and the [https://github.com/JF002/InfiniTime/releases latest Infinitime here].

* Reboot the watch by holding the button until the pine cone arrow appears.
* Flash the reloader zip: <code>reloader-infinitime-recovery-0.14.1.zip</code>
* After flashing, the reloader will run (blue smaller pine cone), then it'll boot the InfiniTime bootloader (large pine cone) will run.
* Boot the watch into recovery mode by holding the button until the pine cone turns red. It'll boot again (large pine cone will turn green) and then the InfiniTime logo will appear.
* You can now flash InfiniTime 1.1.0 (or any other version): <code>pinetime-mcuboot-app-dfu-1.1.0.zip</code>
* InfiniTime should now boot. Enjoy!

[[Category:PineTime]][[Category:Guide]]

PineTime

2021-10-12T08:42:18Z

Kieranc: Add detail about new accelerometer.

[[File:Pinetime.png|400px|thumb|right|The PineTime]]

The '''PineTime''' is a free and open source smartwatch capable of running custom-built open operating systems. Some of the notable features include a heart rate monitor, a week-long battery, and a capacitive touch IPS display that is legible in direct sunlight. It is a fully community driven side-project which anyone can contribute to, allowing you to keep control of your device.

== Frequently asked questions / Getting started ==

'''Read these first!'''

* [[Upgrade PineTime to InfiniTime 1.0.0|Upgrading your new PineTime to InfiniTime 1.0.0]]
* [[PineTime FAQ| Frequently Asked Questions about the PineTime]]
* [[PineTime Devkit Wiring]]
* [[Reprogramming the PineTime|Reprogramming the PineTime (development kit)]]
* [[Switching your PineTime between InfiniTime and Wasp-os]]

== 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.

You can find a list of available firmware and other software here: [[PineTime Development]]

== Companion Apps ==

PineTime/InfiniTime needs a companion app to e.g. upload a firmware, get notifications from a phone, or just get the date/time.
Here are some companion apps:

* [https://www.gadgetbridge.org Gadgetbridge] (Android >= 4.4) - Companion mobile app, supports updating firmware/bootloader, send notifications, etc.
* [https://openrepos.net/content/piggz/amazfish Amazfish] (SailfishOS and Linux) - Companion mobile and desktop app, supports updating firmware/bootloader, send notifications, etc.
* [https://github.com/alexr4535/siglo Siglo] (Linux) - Companion desktop app.
* [https://github.com/ZephyrLabs/PinetimeFlasher PinetimeFlasher] (Windows) - Companion desktop app, only supports flashing firmware.
* [https://apps.apple.com/us/app/nrf-connect-for-mobile/id1054362403 nRFConnect] (iOS) - Only supports flashing firmware.
* [https://github.com/xan-m/Infini-iOS Infini-iOS] (iOS) - Companion mobile app in early development which will support updating firmware/bootloader, send notifications, etc.

== Short overview / Specifications ==
'''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 3.8V LiPo

= Community =

== Forum ==
* [https://forum.pine64.org/forumdisplay.php?fid=134 PineTime forum]

== Chat ==
* [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]

=== Developers and coding ===
* [https://app.element.io/#/room/#pinetime-dev:matrix.org Matrix Channel] (No login required to read)
* [https://t.me/pinetime_dev 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://www.ncartron.org/one-week-with-my-pinetime---a-feedback.html Using the PineTime in production (January 2021)]
* [https://lupyuen.github.io/articles/sneak-peek-of-pinetime-smart-watch-and-why-its-perfect-for-teaching-iot Sneak Peek of PineTime Smart Watch… And why it’s perfect for teaching IoT]
* [https://lupyuen.github.io/articles/building-a-rust-driver-for-pinetimes-touch-controller Building a Rust Driver for PineTime’s Touch Controller]
* [https://lupyuen.github.io/articles/porting-druid-rust-widgets-to-pinetime-smart-watch Porting (druid) Rust Widgets to PineTime Smart Watch]
* [https://lupyuen.github.io/articles/optimising-pinetimes-display-driver-with-rust-and-mynewt Optimising PineTime’s Display Driver with Rust and Mynewt]
* [https://electronut.in/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]
* [https://pankajraghav.com/2021/04/03/PINETIME-STOPCLOCK.html Creating a stopwatch in Pinetime (with Infinitime)]

= 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.

'''NOTE: ''' The I²C bus, also known as TWI bus has known issues, make sure to write your TWI driver with timeouts.

=== 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 in devices shipped before July 2021 is a Bosch BMA421, connected to the I2C bus.
Devices shipped after July 2021 use a Bosch BMA425 accelerometer.

=== 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.4.pdf nRF52832 Product Specification v1.4]
* 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]

= Community case design =

* [https://www.thingiverse.com/thing:4172849 PineTime Smart Watch case by dara0s at thingiverse]
* [https://www.thingiverse.com/thing:4651462 PineTime dev kit back fix by joaquimorg at thingiverse]
* [https://www.thingiverse.com/thing:4763267 PineTime dev kit charging holder v4 by zevix81 at thingiverse]

[[Category:PineTime]]

Upgrade PineTime to InfiniTime 1.0.0

2021-09-16T13:30:22Z

Kieranc: Add note specifying which devices these instructions are applicable to

{{Note|Page under construction, information subject to review and feedback.}}

'''Devices shipped before July 2021 were pre-installed with InfiniTime 0.7.1, and an older bootloader. This features green text 'PINE TIME' on boot, and should be updated to the new bootloader as described below.'''

'''Devices shipped after July 2021 were pre-installed with InfiniTime 1.2 and the new bootloader, which can be identified by the green Pinecone image on boot. The instructions below are unnecessary for these devices.'''

Congratulations on receiving your new PineTime!

So now you're probably wondering exactly how on earth do you go about upgrading your watch to the latest and greatest version of InfiniTime - you know, that version you've seen all those great pictures, videos and reviews of. To those of us that are developing stuff for it, it's pretty easy and straightforward, but like with all technology, it is a bit tricky.

{{warning|1=Some people ran into issues during the update process that would temporarily make their watch unusable (display frozen or blank). The only know workaround consists of waiting for the battery to drain completely and try again. With the display off, and battery fully charged, you can expect a wait of 5-7 days so it is best to not fully charge it. If it freezes with the display on, it will likely be flat by the end of the day. We've never heard of any PineTimes that were permanently bricked (were not recoverable), though. }}

In a nutshell, you need to:
# Charge your watch, but '''not''' to 100% - keep it at approximately 50% - for the reason described above.
# Update InfiniTime
# Update the bootloader
# Install the recovery firmware

= Update Process =
So how do you do this? Where do you start? Well, with a sealed PineTime, your only easy option is via Over The Air (OTA) Device Firmware Update (DFU), which is done via Bluetooth. There are a couple of different ways and apps you can use to do this. If you have an Android device, you can use [https://f-droid.org/en/packages/nodomain.freeyourgadget.gadgetbridge/ Gadgetbridge] or [https://play.google.com/store/apps/details?id=no.nordicsemi.android.mcp NRFConnect] (NRFConnect is available on iOS devices as well). Otherwise, if your laptop or desktop computer has Bluetooth and runs Linux, you can use [https://github.com/alexr4535/siglo Siglo] or [https://github.com/piggz/harbour-amazfish Amazfish]. You can also use these applications on your Pinebook Pro or Pinephone if you happen to have those devices.

The reason for installing the updates in the specified order is because newer versions of InfiniTime have a more robust Bluetooth update process, and since we're updating everything over Bluetooth, the fewer retries and failures from that you have the better. It will still sometimes disconnect mid update, meaning you'll need to try again, and possibly restart the watch a few times as well. And since the recovery firmware is new to the 1.0.0 version of the bootloader, it's best to update that last.

[https://video.codingfield.com/videos/watch/831077c5-16f3-47b4-9b2b-c4bbfecc6529 This video] shows the bootloader and recovery firmware installation procedure.

[https://video.codingfield.com/videos/watch/f7bffb3d-a6a1-43c4-8f01-f4aeff4adf9e This video] shows the bootloader installation and firmware update using Amazfish.

You can also read a [https://github.com/JF002/pinetime-mcuboot-bootloader/blob/339224cf5ed21f4e8b2d22eaeab9869120f7f752/docs/howToUpdate.md detailed installation procedure in the documentation of the bootloader].

== Update InfiniTime ==
To update the main InfiniTime app, you want to flash [https://github.com/JF002/InfiniTime/releases/download/1.0.0/pinetime-mcuboot-app-dfu-1.0.0.zip pinetime-mcuboot-app-dfu-1.0.0.zip].

After updating InfiniTime, ensure that you validate the firmware to prevent it from being automatically reverted/rolled back if your watch is reset/restarted. To do this, swipe right to access the quick actions panel, press the gear/settings icon, swipe up once to show the second page, press on the 'Firmware' option and then on 'Validate'.

[https://youtu.be/-5lwBd60k0Q Video showing validation process]

=== Gadgetbridge ===

# Connect your PineTime to GB
# Download the aforementioned file to your phone
# Find the file in your file manager
# 'Open With' Gadgetbridge F/W Installer (method varies by device) - on my phone, it is press and hold, select the file, and then choose 'open with app' from the more options menu
# Confirm that you wish to apply the update
# Wait for the update to complete

[https://youtu.be/nAaaC7D5sVo Video showing how to start the update]

=== NRFConnect ===

# Download the aforementioned file to your phone.
# Open NRFConnect
# Scan for your device
# Connect to it
# Choose the DFU option at the top right of the screen
# Ensure the 'Distribution packet (ZIP)' option is selected, and press OK
# Select your previously downloaded file
# Wait for the update to complete

[https://youtu.be/jnX7WwYDiDE Video showing how to start the update]

=== Siglo ===
# If your device was not detected upon start, press "Rescan" to find it.
# Select the "1.0.0" tag
# Select the aforementioned file/asset.
# Select "Flash It!"

=== Amazfish ===
# Run Amazfish (service + UI)
# Pair with you device:
## Unzip the DFU file to extract the .bin file.
## Click on "pair with watch" on the top
## Select "PineTime" (if your device is running InfiniTime 0.7.1 or lower) or "InfiniTime (if it's running InfiniTime 0.8+) and choose your device in the list
# Click on "Download file" on the top
# Click on "Choose file" and select the .bin file you extracted from the DFU file
# Click on "Send file"
# Wait for the update to complete.

[https://video.codingfield.com/videos/watch/41cfcf5d-b0e6-4323-8056-b0a6682d1f25 See it in action!]

== Update the bootloader ==
To update the bootloader, you want to flash [https://github.com/JF002/InfiniTime/releases/download/0.14.1/reloader-mcuboot.zip reloader-mcuboot.zip].
Once the bootloader is updated, you should notice that the boot logo has changed. Previously, it was a green "PineTime" logo, and now it is a large pinecone that is progressively drawn in green.

[https://youtu.be/fvHQ8ZeqnOo Video showing what the InfiniTime 1.0.0 bootloader looks like]

=== Using Gadgetbridge ===

Same process as before, but with the file for this step.

=== Using NRFConnect ===

Same process as before, but with the file for this step.

=== Using Siglo ===
Same process as before, but select the "0.14.1" tag, and the file/asset for this step.

=== Using Amazfish ===

You may need to re-pair with your device by selecting "InfiniTime" (since you've already upgraded to InfiniTime 1.0) in the device type list. Then follow the same process as before, but with the file for this step.

== Install the recovery firmware ==
{{warning|1=Don't do this before updating the bootloader, otherwise your PineTime will freeze at the end of the process, and you will need to wait for the battery to go flat }}

To install the recovery firmware, you want to flash [https://github.com/JF002/InfiniTime/releases/download/0.14.1/pinetime-mcuboot-recovery-loader-dfu-0.14.1.zip pinetime-mcuboot-recovery-loader-dfu-0.14.1.zip]. You will know when this is running when it shows an InfiniTime logo with a progress bar running across the bottom whilst it is installing the recovery firmware.

=== Using Gadgetbridge ===

Same process as before, but with the file for this step.

=== Using NRFConnect ===

Same process as before, but with the file for this step.

=== Using Siglo ===
Same process as before, but with the file/asset for this step.

=== Using Amazfish ===

Same process as before, but with the file for this step.

= Guides and Videos =

= Troubleshooting =
Sometimes during the update process, the connection will drop, and the update will fail. Your PineTime isn't broken, most likely the Bluetooth link dropped for a moment, so just try again. Try rebooting your phone, if it keeps failing, try restarting the watch by holding the power button down for approximately 8 seconds. Try to '''avoid''' holding down the button with the screen off. Or try with another device, just in case there are compatibility issues.

Version 1.0.0 of InfiniTime is merely the first version that was considered sufficiently feature-complete and stable enough for daily use. This isn't to say there aren't still bugs present ('cause there are!). So there are a few bugs still present in the update process and the bootloader. One unfortunate bug appears to be that sometimes when the watch tries to restart after an update, the bootloader locks up, and the watch won't turn on. In this case, you will need to wait until the watch battery goes flat, to force the watch to reset. This will most likely involve waiting for a week, and then when you put the watch on the charging cradle, it will power up and you should be right to try again.

If you get stuck or have any questions, join us on your preferred [[Main_Page#Chat_Platforms|chat platform]] or the product [https://forum.pine64.org/forumdisplay.php?fid=134 forum]. There's usually someone available who can help, or will get back to you in a few hours.

[[Category:PineTime]][[Category:Guide]]

PineTimeStyle

2021-08-31T09:06:33Z

Kieranc:

2021-04-09T11:30:09Z

Kieranc: /* Cloning the repository */

=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 '''WatchFaceDigital.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===
Instructions for cloning the repository are available on the [https://github.com/JF002/InfiniTime/blob/develop/doc/buildAndProgram.md Building and programming page] on github.

===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==

[[Category:PineTime]]

PineTime Custom Watchface Tutorial

2021-04-09T11:24:27Z

Kieranc: Change reference to file where the watchface is stored

=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 '''WatchFaceDigital.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==

[[Category:PineTime]]