PINE64 - User contributions [en]

PineTime

2021-06-25T10:10:41Z

JoshComer: Corrected a typo for the PinetimeFlasher line. Also added a line showing that there is an option to flash firmware to iOS through nRFConnect

== 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 devkit]]
* [[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) - Companion mobile app, only supports flashing firmware.

== 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://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://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 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.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-06-25T10:03:48Z

JoshComer: Clarified that NRFConnect is available on iOS to upgrade PineTime

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

Congratulations on receiving your new PineTime!

From the factory, it ships with InfiniTime 0.7.1, and an older bootloader. 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]]