PINE64 - User contributions [en]

PineTime

2020-01-26T00:42:36Z

Darnel: /* Frequently asked questions */ Fix link

== Frequently asked questions ==

'''Read this first!'''

* [https://wiki.pine64.org/index.php/Frequently_asked_questions_about_the_PineTime Click here to see frequently asked questions about the dev kit]
* [https://wiki.pine64.org/index.php/Lup_Yuen_Lee_Q%26A_about_PineTime Lup Yuen Lee Q&A about PineTime]

== Specifications ==
'''Dimensions:''' 37.5 x 40 x 11mm 
'''Weight:''' 38 grams 
'''IP Rating:''' IP67 (waterproof to 1 meter) 
'''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:''' 5.0 (including Bluetooth Low Energy) 
'''Sensors:''' Accelerometer, Heart rate sensor 
'''Feedback:''' Vibration motor 
'''Battery:''' 170-180mAh LiPo

== SWD Pinout ==
The devkits have exposed SWD pins for flashing and debugging. The pinout is:
[[File:PineTime_SWD_location.jpg]]

== Driving the peripherals ==

=== 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)
| Clock/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.

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

=== How to write battery friendly software? ===

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

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

=== Button ===

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

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

=== Touch panel ===

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

==== Pins ====

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

==== I²C ====

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

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

==== Touch events ====

Touch informations are available in 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: on a slippery,

0x02: decline,

0x03: Left slip,

0x04: Right slide,

0x05: Click,

0x0B: Double-click,

0x0C: 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
|0x05 = SLEEP
|-
|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 : ''' 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!

== Programming firmware ==

=== Using JLink programmer and nrfjprog tools ===

The following steps have been tested with the Segger JLink embedded in the [https://www.nordicsemi.com/Software-and-Tools/Development-Kits/nRF52-DK NRF52-DK development board].

1. Connect the Pinetime SWD pins to the debugger (P20 on NRF52-DK)

{| class="wikitable"
!Pintime
!JLink
|-
|GND
|GND
|-
|SWDCLK
|SWDCLK
|-
|SWDIO
|SWDIO
|-
|VCC (3.3V)
|VTG (target detect)
|}

2. Unlock the device and erase the memory. '''You need to execute this step only once, to remove the read protection on the memory. Note that it will erase the whole flash memory of the MCU!''' :

nrfjporg -f NRF52 --recover

3. Program the BLE softdevice (if needed by the firmware). Replace PATH_TO_NRF_SDK by the path where you unzipped the [https://www.nordicsemi.com/Software-and-Tools/Software/nRF5-SDK NRF52 SDK] :

nrfjprog -f NRF52 --program /PATH_TO_NRF_SDK/components/softdevice/s132/hex/s132_nrf52_6.1.1_softdevice.hex --sectorerase

4. Program the firmware (replace firmware.hex by the actual filename of the firmware):

nrfjprog -f NRF52 --program firmware.hex --sectorerase

5. Reset and run the new firmware:

nrfjprog -f NRF52 --reset

=== Using OpenOCD and a Raspberry Pi ===

Instructions in [https://medium.com/@ly.lee/build-and-flash-rust-mynewt-firmware-for-pinetime-smart-watch-5e14259c55 Medium post], subsequently [https://medium.com/@ly.lee/openocd-on-raspberry-pi-better-with-swd-on-spi-7dea9caeb590 updated] with a more reliable method under development, so may be a bit of a moving target.

=== Using STM32 bluepill as blackmagic probe ===

Instructions in [https://forum.pine64.org/showthread.php?tid=8816&pid=57095#pid57095 forum post] or [https://gist.github.com/darnel/dac1370d057e176386ca4026418abc2b gist] (mac os)

== Manual / Articles ==

* [https://github.com/najnesnaj/pinetime-zephyr Beginner manual explained how you to programs and install zephyr on PineTime Dev Kit, big thanks to najnesnaj :-)]

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

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

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

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

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

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

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

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

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

== Development efforts ==

{| class="wikitable"
!
! Project Homepage
! Project Source
! PineTime Implementations

|-
! FreeRTOS
|https://www.freertos.org
| https://sourceforge.net/projects/freertos/
| [https://github.com/JF002/Pinetime JF002/Pinetime]
[https://github.com/kaythe/pinetime-os kaythe/pinetime-os]

|-
! Zephyr
| https://www.zephyrproject.org
| https://github.com/zephyrproject-rtos/zephyr
| [https://github.com/najnesnaj/pinetime-zephyr najnesnaj/pinetime-zephyr]
[https://github.com/SuperPrower/pinetime_zephyr_sample_fw SuperPrower/pinetime_zephyr_sample_fw]

|-
! mynewt
| https://mynewt.apache.org/about/
| https://github.com/apache/mynewt-core
| [https://github.com/lupyuen/pinetime-rust-mynewt lupyuen/pinetime-rust-mynewt]

|-
! MbedOS
| https://os.mbed.com
| https://github.com/ARMmbed/mbed-os
| [https://github.com/sethitow/awesome-pinetime sethitow/mbed-pinetime]

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

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

|-
! MicroPython
| https://micropython.org/
| https://github.com/micropython/micropython
| [https://github.com/daniel-thompson/wasp-os daniel-thompson/wasp-os]
|-
! AdaFruit bootloader
|
| https://github.com/adafruit/Adafruit_nRF52_Bootloader
| [https://github.com/daniel-thompson/wasp-bootloader daniel-thompson/wasp-bootloader]
|-
|}

== Datasheets and Schematics ==

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

=== Component Datasheets ===
* NORDIC SoC information:
** [http://files.pine64.org/doc/datasheet/pinetime/nRF52832%20product%20brief.pdf NORDIC nRF52832 Product Brief]
* PMU (Power Management Unit) information:
** [http://files.pine64.org/doc/datasheet/pinetime/SGM40561.pdf SGMicro SGM40561 Single Cell Charger Datasheet]
** [http://files.pine64.org/doc/datasheet/pinetime/SGMICRO-SGM2036.pdf SGMicro SGM2036 3.3V Low Power Low Dropout RF Linear Regulator Datasheet]
* SPI Flash information:
** [http://files.pine64.org/doc/datasheet/pinetime/MX25L6433F,%203V,%2064Mb,%20v1.6.pdf Macronix 64Mb(8MB) SPI NOR Flash]
** [http://files.pine64.org/doc/datasheet/pinetime/MX25L12835F,%203V,%20128Mb,%20v1.6.pdf Macronix 128Mb(16MB) SPI NOR Flash]
* LCD Panel:
** [http://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:
** [http://files.pine64.org/doc/datasheet/pinetime/PineTime%20Touch%20Panel.jpg Touchpad Specification for PineTimel]
** [http://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/5/51/CST816S%E6%95%B0%E6%8D%AE%E6%89%8B%E5%86%8CV1.1.en.pdf English Translation]
* Sensor:
** [http://files.pine64.org/doc/datasheet/pinetime/BST-BMA421-FL000.pdf BOSCH BMA421 Triaxial VAcceleration Sensor Product Brief]
** [http://files.pine64.org/doc/datasheet/pinetime/HRS3300%20Heart%20Rate%20Sensor.pdf TianYiHeXin HRS3300 PPG Heart Rate Sensor Data Sheet]

= Community =
* [https://forum.pine64.org/forumdisplay.php?fid=134 PineTime forum]
* [https://riot.im/app/#/room/#pinetime64:matrix.org Matrix Channel] (No login required to read)
* IRC: Server us.pine64.xyz. Type /list to see all channels
* [https://t.me/pinetime Telegram group]
* [https://discordapp.com/invite/DgB7kzr Discord server invite link]

PineTime

2020-01-26T00:41:35Z

Darnel: /* Frequently asked questions */ Adding link to collected Lup Yuen Lee's Q&A

== Frequently asked questions ==

'''Read this first!'''

* [https://wiki.pine64.org/index.php/Frequently_asked_questions_about_the_PineTime Click here to see frequently asked questions about the dev kit]
• [https://wiki.pine64.org/index.php/Lup_Yuen_Lee_Q%26A_about_PineTime]

== Specifications ==
'''Dimensions:''' 37.5 x 40 x 11mm 
'''Weight:''' 38 grams 
'''IP Rating:''' IP67 (waterproof to 1 meter) 
'''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:''' 5.0 (including Bluetooth Low Energy) 
'''Sensors:''' Accelerometer, Heart rate sensor 
'''Feedback:''' Vibration motor 
'''Battery:''' 170-180mAh LiPo

== SWD Pinout ==
The devkits have exposed SWD pins for flashing and debugging. The pinout is:
[[File:PineTime_SWD_location.jpg]]

== Driving the peripherals ==

=== 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)
| Clock/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.

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

=== How to write battery friendly software? ===

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

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

=== Button ===

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

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

=== Touch panel ===

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

==== Pins ====

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

==== I²C ====

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

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

==== Touch events ====

Touch informations are available in 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: on a slippery,

0x02: decline,

0x03: Left slip,

0x04: Right slide,

0x05: Click,

0x0B: Double-click,

0x0C: 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
|0x05 = SLEEP
|-
|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 : ''' 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!

== Programming firmware ==

=== Using JLink programmer and nrfjprog tools ===

The following steps have been tested with the Segger JLink embedded in the [https://www.nordicsemi.com/Software-and-Tools/Development-Kits/nRF52-DK NRF52-DK development board].

1. Connect the Pinetime SWD pins to the debugger (P20 on NRF52-DK)

{| class="wikitable"
!Pintime
!JLink
|-
|GND
|GND
|-
|SWDCLK
|SWDCLK
|-
|SWDIO
|SWDIO
|-
|VCC (3.3V)
|VTG (target detect)
|}

2. Unlock the device and erase the memory. '''You need to execute this step only once, to remove the read protection on the memory. Note that it will erase the whole flash memory of the MCU!''' :

nrfjporg -f NRF52 --recover

3. Program the BLE softdevice (if needed by the firmware). Replace PATH_TO_NRF_SDK by the path where you unzipped the [https://www.nordicsemi.com/Software-and-Tools/Software/nRF5-SDK NRF52 SDK] :

nrfjprog -f NRF52 --program /PATH_TO_NRF_SDK/components/softdevice/s132/hex/s132_nrf52_6.1.1_softdevice.hex --sectorerase

4. Program the firmware (replace firmware.hex by the actual filename of the firmware):

nrfjprog -f NRF52 --program firmware.hex --sectorerase

5. Reset and run the new firmware:

nrfjprog -f NRF52 --reset

=== Using OpenOCD and a Raspberry Pi ===

Instructions in [https://medium.com/@ly.lee/build-and-flash-rust-mynewt-firmware-for-pinetime-smart-watch-5e14259c55 Medium post], subsequently [https://medium.com/@ly.lee/openocd-on-raspberry-pi-better-with-swd-on-spi-7dea9caeb590 updated] with a more reliable method under development, so may be a bit of a moving target.

=== Using STM32 bluepill as blackmagic probe ===

Instructions in [https://forum.pine64.org/showthread.php?tid=8816&pid=57095#pid57095 forum post] or [https://gist.github.com/darnel/dac1370d057e176386ca4026418abc2b gist] (mac os)

== Manual / Articles ==

* [https://github.com/najnesnaj/pinetime-zephyr Beginner manual explained how you to programs and install zephyr on PineTime Dev Kit, big thanks to najnesnaj :-)]

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

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

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

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

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

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

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

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

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

== Development efforts ==

{| class="wikitable"
!
! Project Homepage
! Project Source
! PineTime Implementations

|-
! FreeRTOS
|https://www.freertos.org
| https://sourceforge.net/projects/freertos/
| [https://github.com/JF002/Pinetime JF002/Pinetime]
[https://github.com/kaythe/pinetime-os kaythe/pinetime-os]

|-
! Zephyr
| https://www.zephyrproject.org
| https://github.com/zephyrproject-rtos/zephyr
| [https://github.com/najnesnaj/pinetime-zephyr najnesnaj/pinetime-zephyr]
[https://github.com/SuperPrower/pinetime_zephyr_sample_fw SuperPrower/pinetime_zephyr_sample_fw]

|-
! mynewt
| https://mynewt.apache.org/about/
| https://github.com/apache/mynewt-core
| [https://github.com/lupyuen/pinetime-rust-mynewt lupyuen/pinetime-rust-mynewt]

|-
! MbedOS
| https://os.mbed.com
| https://github.com/ARMmbed/mbed-os
| [https://github.com/sethitow/awesome-pinetime sethitow/mbed-pinetime]

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

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

|-
! MicroPython
| https://micropython.org/
| https://github.com/micropython/micropython
| [https://github.com/daniel-thompson/wasp-os daniel-thompson/wasp-os]
|-
! AdaFruit bootloader
|
| https://github.com/adafruit/Adafruit_nRF52_Bootloader
| [https://github.com/daniel-thompson/wasp-bootloader daniel-thompson/wasp-bootloader]
|-
|}

== Datasheets and Schematics ==

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

=== Component Datasheets ===
* NORDIC SoC information:
** [http://files.pine64.org/doc/datasheet/pinetime/nRF52832%20product%20brief.pdf NORDIC nRF52832 Product Brief]
* PMU (Power Management Unit) information:
** [http://files.pine64.org/doc/datasheet/pinetime/SGM40561.pdf SGMicro SGM40561 Single Cell Charger Datasheet]
** [http://files.pine64.org/doc/datasheet/pinetime/SGMICRO-SGM2036.pdf SGMicro SGM2036 3.3V Low Power Low Dropout RF Linear Regulator Datasheet]
* SPI Flash information:
** [http://files.pine64.org/doc/datasheet/pinetime/MX25L6433F,%203V,%2064Mb,%20v1.6.pdf Macronix 64Mb(8MB) SPI NOR Flash]
** [http://files.pine64.org/doc/datasheet/pinetime/MX25L12835F,%203V,%20128Mb,%20v1.6.pdf Macronix 128Mb(16MB) SPI NOR Flash]
* LCD Panel:
** [http://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:
** [http://files.pine64.org/doc/datasheet/pinetime/PineTime%20Touch%20Panel.jpg Touchpad Specification for PineTimel]
** [http://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/5/51/CST816S%E6%95%B0%E6%8D%AE%E6%89%8B%E5%86%8CV1.1.en.pdf English Translation]
* Sensor:
** [http://files.pine64.org/doc/datasheet/pinetime/BST-BMA421-FL000.pdf BOSCH BMA421 Triaxial VAcceleration Sensor Product Brief]
** [http://files.pine64.org/doc/datasheet/pinetime/HRS3300%20Heart%20Rate%20Sensor.pdf TianYiHeXin HRS3300 PPG Heart Rate Sensor Data Sheet]

= Community =
* [https://forum.pine64.org/forumdisplay.php?fid=134 PineTime forum]
* [https://riot.im/app/#/room/#pinetime64:matrix.org Matrix Channel] (No login required to read)
* IRC: Server us.pine64.xyz. Type /list to see all channels
* [https://t.me/pinetime Telegram group]
* [https://discordapp.com/invite/DgB7kzr Discord server invite link]

PineTime FAQ

2020-01-26T00:40:09Z

Darnel: Included (and little edited) some questions and answers from Lup Yuen Lee

'''Does the PineTime run Linux?'''

No. Please read this forum article for information about Linux on PineTime: https://forum.pine64.org/showthread.php?tid=8112

'''How long does it take to ship my PineTime?'''

That depends on whether you chose for Standard or Express shipping. Standard shipping for the dev kit may take up to a few weeks.

'''My PineTime arrived, now what?'''

You should start by testing out all the features of the watch, to make sure everything works. You can do this using the software that was preinstalled on your device. '''Don't solder wires to the pins unless you really know how to do so safely!''' The wire that comes with the devkit already works for removing the protection and flashing code, only takes plugging it into the holes and holding it still gently. After the flash lock has been removed you can experiment with your own software or someone else's.

'''How do I remove flash protection?'''

The flash protection can be removed using multiple different methods. If you don't have anything except the PineTime, not even a RPi, then you have to order a programmer online. The main article about [[PineTime]] contains links to different tutorials. You can also remove flash protection using a J-Link, CMSIS-DAP dongle and various other programmers.

'''Why can't you use ST-Link to remove nRF52 Flash Protection?'''

Because ST-Link is a High Level Adapter. It doesn't really implement all SWD functions, just a subset. For performance I think. More details in the section "Why Visual Studio Code with ST-Link (instead of nRFgo Studio with J-LINK)" in the article "Coding nRF52 with Rust and Apache Mynewt on Visual Studio Code" here: https://medium.com/@ly.lee/coding-nrf52-with-rust-and-apache-mynewt-on-visual-studio-code-9521bcba6004?source=friends_link&sk=bb4e2523b922d0870259ab3fa696c7da

'''Since we need a low level SWD adapter like Raspberry Pi anyway, can we do everything on a Pi instead of ST-Link + Windows?'''

Current progress with Pi and PineTime is here https://medium.com/@ly.lee/debug-rust-mynewt-firmware-for-pinetime-on-raspberry-pi-4b9ac2d093a9?source=friends_link&sk=edb508c31e43d3ec40ecd8554f3405f6

'''What's the OS that's preinstalled on the PineTime by default?'''

The watch, and its preinstalled OS, is built by a friend of TL. The software is proprietary and not made by Pine64 or its community. It can interact with the "Da Fit" app on Android. The dev kit contains this OS (and as a result, the flash protection) so that developers can test if all the hardware on their device is working correctly before they flash the device and start working on their own software.

'''Can we use this OS or its source code?'''

While it's not what the dev kit is for, you are of course free to use the watch with its preinstalled software as is. The preinstalled OS is proprietary, and its owner will not release the source code, so we cannot use this OS as a starting point.

'''Why is the back exposed? Is it supposed to snap on?'''

The back cover of the PineTime dev kit is exposed so that you can flash and debug the device with the SWD pins. The main unit and cover does not snap (lock) together. If you want to attach the back cover anyway, you can use glue or tape.

'''What hardware should I use to flash code to the PineTime?'''

There are several ways you can do this:

a) Use a J-Link. These can remove flash protection as well, so you won't need a Raspberry Pi to start working on the PineTime. A cheap option for this is the J-Link EDU: https://www.segger.com/products/debug-probes/j-link/models/j-link-edu/.

b) Use an even cheaper CMSIS-DAP dongle (sometimes called DAPLINK) from AliExpress, that too allows removing the flash protection and flashing new software using OpenOCD. Search for "CMSIS-DAP" or "DAPLINK" on AliExpress.

c) Use a Raspberry Pi with OpenOCD

d) Use a ST-Link V2 clone. Search for "ST-Link V2" on AliExpress or Amazon to buy one of these.

e) Finally, you can use an STM32F103 "Blue Pill" with BMP (Black Magic Probe). Here's a nice guide for that: https://devzone.nordicsemi.com/nordic/nordic-blog/b/blog/posts/flashing-and-debugging-nrf5152-with-a-cheap-blackm

'''I have experience developing on Arduino. How does the PineTime compare?'''

Arduino provides the Arduino IDE (or you use the avr-gcc and avrdude command-line tools) which you can use to compile and upload code to an Arduino board. The PineTime and its ARM processor doesn't have this, so you'll have to familiarize yourself with tools like GCC for AVR, and OpenOCD. Some experience with Arduino does translate over to the PineTime, especially if you've worked with LCD's, or SPI. The PineTime is at least four times faster than an Arduino Uno (even faster at certain specific workloads due to hardware acceleration), and it has 32 times more RAM and 16 times more flash storage.

'''My PineTime has the stock proprietary software on it, how do I set the time?'''

You can use either nRF Connect, custom GadgetBridge build or the proprietary Da Fit app.

'''My PineTime's screen shows garbage, how do I fix it?'''

This is usually caused by unplugging the device after it has booted, it needs to be reinitialised. To do so just restart the watch by removing power to it.

'''Is there a 3D model of PineTime available somewhere?'''

Not yet.

'''Is there a standard agreed method of pushing OTA updates so that one could seal the PineTime dev kit nicely?'''

Not yet.

'''What is Arm Semihosting?'''

So we know that we use the SWD (Single Wire Debug) protocol created by Arm for flashing and debugging Arm embedded CPUs. SWD being derived from standard JTAG, but with fewer wires
With Arm CPUs you can trigger an software interrupt, and allow the debugger (OpenOCD) to do something really nifty
Display a message, read console input, dump out a file, even read a file! Thats called Arm Semihosting http://www.keil.com/support/man/docs/armcc/armcc_pge1358787046598.htm

'''What is OpenOCD?'''
OpenOCD is Open On-Chip Debugger. It's the software that drives your microcontroller debugger/flasher. We need it for running any kind of flashing and debugging with Pi or ST-Link. gdb talks to OpenOCD for debugging firmware. And VSCode talks to gdb for debugging firmware visually. http://openocd.org/doc-release/html/About.html#What-is-OpenOCD_003f
There have been no official updates for years, the closest one is by ntfreak: https://github.com/ntfreak/openocd (My SPI fork is based on this)

'''Can I use Pinebook Pro for developing PineTime?'''

Arm Embedded Toolchain for Pinebook Pro is here, if anyone needs it. It's linked with dynamic libraries, so I fear it might not work on your Pinebook Pro. Hoping to save you 7 hours of painful toolchain building... https://github.com/lupyuen/pinetime-rust-mynewt/releases/tag/v1.0.5

User:Darnel/Lup Yuen Lee Q&A about PineTime

2020-01-26T00:37:27Z

Darnel: Moving general questions to FAQ

;Do I have something against JLink, the official Nordic tools, and Nordic SoftDevice?
: Not really... I'm targeting the mass audience of new IoT learners trying PineTime for the very first time... Because Arduino and BBC micro:bit not so realistic in IoT any more. I think new learners would be more comfortable connecting a Raspberry Pi to PineTime, and using open source tools like VSCode. And if they wish to dig deep into the Bluetooth stack, they can with the open-source NimBLE Bluetooth stack.(edited)

;Why Rust? Not C or C++?
: Because I'm tired of teaching Pointers... and how to get out of trouble with Pointers It's 2020, we should move to something more modern and safer. And if it helps to create more secure IoT gadgets... All the better!

;Why Mynewt? Not FreeRTOS or Zephyr?
: I first tried Rust on FreeRTOS (I have an article on that)... The complexity and naming in FreeRTOS really scared me, and I don't think it's good for learners. Mynewt is a tiny, modern, modular embedded OS that's easier to pick up. It doesn't seem to have as much support as Zephyr, but that also means I get free reign to do interesting things... like run Rust! I'm keen to see how Rust on Zephyr turns out... And I wonder how soon that will happen if so many microcontroller companies have vested interest in Zephyr

;Why not Bare Metal, without an OS? Why not Rust Embedded?
: My response... Why reinvent the wheel? Eventually we will be forced to do some multitasking, like any IoT gadget: reading + sending sensor data concurrently, even downloading firmware in the background. Without multitasking support we'll run into a dead end... Just like Arduino and BBC micro:bit! I learnt that the hard way (I have an article on Arduino State Machines!), so I'll always start with an embedded OS that handles multitasking for me.

;How do we deal with a 64k framebuffer when we need 240x240x2?
: Without a full framebuffer in RAM I think we can do with smaller chunks of framebuffers. Let's say we got a logo in the centre of a black screen. The logo will make up one rectangular chunk, the rest of the black screen can be rendered as separate rectangular chunks too. Not sure if it makes sense, but it's similar to the chunking in my article... https://medium.com/@ly.lee/optimising-pinetimes-display-driver-with-rust-and-mynewt-3ba269ea2f5c?source=friends_link&sk=4d2cbd2e6cd2343eed62d214814f7b81

;What is #![no_std]?
: In the Rust world there's desktop Rust, which uses the Standard Rust Library... all the glorious malloc heap stuff. Growing vectors! Growing Strings! But on embedded we can't sign blank cheques to grow things on demand, so we use no_std: The Core Rust Library
: No heap, no growing vectors, no Strings (well limited)
: there are workarounds, which is what I have done to port the druid library
: Aren't we glad that Rust actually makes a distinction between desktop and embedded programs? We dont see that in C

User:Darnel/Lup Yuen Lee Q&A about PineTime

2020-01-25T14:29:47Z

Darnel: Created page with ";Why can't you use ST-Link to remove nRF52 Flash Protection? : Because ST-Link is a High Level Adapter. It doesn't really implement all SWD functions, just a subset. For perfo..."

;Why can't you use ST-Link to remove nRF52 Flash Protection?
: Because ST-Link is a High Level Adapter. It doesn't really implement all SWD functions, just a subset. For performance I think. More details in the section "Why Visual Studio Code with ST-Link (instead of nRFgo Studio with J-LINK)" in the article "Coding nRF52 with Rust and Apache Mynewt on Visual Studio Code" here: https://medium.com/@ly.lee/coding-nrf52-with-rust-and-apache-mynewt-on-visual-studio-code-9521bcba6004?source=friends_link&sk=bb4e2523b922d0870259ab3fa696c7da

;Since we need a low level SWD adapter like Raspberry Pi anyway, that inspired me... Can we do EVERYTHING on a Pi instead of ST-Link + Windows?
: And I'm glad it turned out very well
: Here's my current progress with Pi and PineTime... https://medium.com/@ly.lee/debug-rust-mynewt-firmware-for-pinetime-on-raspberry-pi-4b9ac2d093a9?source=friends_link&sk=edb508c31e43d3ec40ecd8554f3405f6

;Do I have something against JLink, the official Nordic tools, and Nordic SoftDevice?
: Not really... I'm targeting the mass audience of new IoT learners trying PineTime for the very first time... Because Arduino and BBC micro:bit not so realistic in IoT any more. I think new learners would be more comfortable connecting a Raspberry Pi to PineTime, and using open source tools like VSCode. And if they wish to dig deep into the Bluetooth stack, they can with the open-source NimBLE Bluetooth stack.(edited)

;Why Rust? Not C or C++?
: Because I'm tired of teaching Pointers... and how to get out of trouble with Pointers It's 2020, we should move to something more modern and safer. And if it helps to create more secure IoT gadgets... All the better!

;Why Mynewt? Not FreeRTOS or Zephyr?
: I first tried Rust on FreeRTOS (I have an article on that)... The complexity and naming in FreeRTOS really scared me, and I don't think it's good for learners. Mynewt is a tiny, modern, modular embedded OS that's easier to pick up. It doesn't seem to have as much support as Zephyr, but that also means I get free reign to do interesting things... like run Rust! I'm keen to see how Rust on Zephyr turns out... And I wonder how soon that will happen if so many microcontroller companies have vested interest in Zephyr

;Why not Bare Metal, without an OS? Why not Rust Embedded?
: My response... Why reinvent the wheel? Eventually we will be forced to do some multitasking, like any IoT gadget: reading + sending sensor data concurrently, even downloading firmware in the background. Without multitasking support we'll run into a dead end... Just like Arduino and BBC micro:bit! I learnt that the hard way (I have an article on Arduino State Machines!), so I'll always start with an embedded OS that handles multitasking for me.

;How do we deal with a 64k framebuffer when we need 240x240x2?
: Without a full framebuffer in RAM I think we can do with smaller chunks of framebuffers. Let's say we got a logo in the centre of a black screen. The logo will make up one rectangular chunk, the rest of the black screen can be rendered as separate rectangular chunks too. Not sure if it makes sense, but it's similar to the chunking in my article... https://medium.com/@ly.lee/optimising-pinetimes-display-driver-with-rust-and-mynewt-3ba269ea2f5c?source=friends_link&sk=4d2cbd2e6cd2343eed62d214814f7b81

;What is #![no_std]?
: In the Rust world there's desktop Rust, which uses the Standard Rust Library... all the glorious malloc heap stuff. Growing vectors! Growing Strings! But on embedded we can't sign blank cheques to grow things on demand, so we use no_std: The Core Rust Library
: No heap, no growing vectors, no Strings (well limited)
: there are workarounds, which is what I have done to port the druid library
: Aren't we glad that Rust actually makes a distinction between desktop and embedded programs? We dont see that in C

;What is Arm Semihosting?
: So we know that we use the SWD (Single Wire Debug) protocol created by Arm for flashing and debugging Arm embedded CPUs. SWD being derived from standard JTAG, but with fewer wires
: With Arm CPUs you can trigger an software interrupt, and allow the debugger (OpenOCD) to do something really nifty
: Display a message, read console input, dump out a file, even read a file! Thats called Arm Semihosting http://www.keil.com/support/man/docs/armcc/armcc_pge1358787046598.htm

;What is OpenOCD?
: OpenOCD is not for obsessive-compulsive disorder (it's Open On-Chip Debugger)... But it's the software that drives your microcontroller debugger/flasher. We need it for running any kind of flashing and debugging with Pi or ST-Link. gdb talks to OpenOCD for debugging firmware. And VSCode talks to gdb for debugging firmware visually. Phew http://openocd.org/doc-release/html/About.html#What-is-OpenOCD_003f

;Do you know that OpenOCD is not officially maintained any more?
: And this is especially scary because it's a core part of the open source ecosystem! There have been no official updates for years, the closest one is by ntfreak: https://github.com/ntfreak/openocd (My SPI fork is based on this)

;Arm Embedded Toolchain for Pinebook Pro
: Arm Embedded Toolchain for Pinebook Pro is here, if anyone needs it. It's linked with dynamic libraries, so I fear it might not work on your Pinebook Pro. Hoping to save you 7 hours of painful toolchain building... https://github.com/lupyuen/pinetime-rust-mynewt/releases/tag/v1.0.5
: I'll save lesson for Arm Embedded Toolchain another day... And why it's called arm-none-eabi!

PineTime

2020-01-23T13:33:25Z

Darnel: Link to my gist notes

== Frequently asked questions ==

* [https://wiki.pine64.org/index.php/Frequently_asked_questions_about_the_PineTime Click here to see frequently asked questions about the dev kit]

== Specifications ==
'''Dimensions:''' 37.5 x 40 x 11mm 
'''Weight:''' 38 grams 
'''IP Rating:''' IP67 (waterproof to 1 meter) 
'''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:''' 5.0 (including Bluetooth Low Energy) 
'''Sensors:''' Accelerometer, Heart rate sensor 
'''Feedback:''' Vibration motor 
'''Battery:''' 170-180mAh LiPo

== SWD Pinout ==
The devkits have exposed SWD pins for flashing and debugging. The pinout is:
[[File:PineTime_SWD_location.jpg]]

== Driving the peripherals ==

=== 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)
| Clock/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.

=== Battery ===

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

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

adcVoltage = adcValue / (4095 / 3.3)

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

batteryVoltage = adcValue * 2 / (4095 / 3.3)

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

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

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

=== Button ===

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

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

=== Touch panel ===

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

==== Pins ====

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

==== I²C ====

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

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

==== Touch events ====

Touch informations are available in 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: on a slippery,

0x02: decline,

0x03: Left slip,

0x04: Right slide,

0x05: Click,

0x0B: Double-click,

0x0C: 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
|0x05 = SLEEP
|-
|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 : ''' 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!

== Programming firmware ==

=== Using JLink programmer and nrfjprog tools ===

The following steps have been tested with the Segger JLink embedded in the [https://www.nordicsemi.com/Software-and-Tools/Development-Kits/nRF52-DK NRF52-DK development board].

1. Connect the Pinetime SWD pins to the debugger (P20 on NRF52-DK)

{| class="wikitable"
!Pintime
!JLink
|-
|GND
|GND
|-
|SWDCLK
|SWDCLK
|-
|SWDIO
|SWDIO
|-
|VCC (3.3V)
|VTG (target detect)
|}

2. Unlock the device and erase the memory. '''You need to execute this step only once, to remove the read protection on the memory. Note that it will erase the whole flash memory of the MCU!''' :

nrfjporg -f NRF52 --recover

3. Program the BLE softdevice (if needed by the firmware). Replace PATH_TO_NRF_SDK by the path where you unzipped the [https://www.nordicsemi.com/Software-and-Tools/Software/nRF5-SDK NRF52 SDK] :

nrfjprog -f NRF52 --program /PATH_TO_NRF_SDK/components/softdevice/s132/hex/s132_nrf52_6.1.1_softdevice.hex --sectorerase

4. Program the firmware (replace firmware.hex by the actual filename of the firmware):

nrfjprog -f NRF52 --program firmware.hex --sectorerase

5. Reset and run the new firmware:

nrfjprog -f NRF52 --reset

=== Using OpenOCD and a Raspberry Pi ===

Instructions in [https://medium.com/@ly.lee/build-and-flash-rust-mynewt-firmware-for-pinetime-smart-watch-5e14259c55 Medium post]

=== Using STM32 bluepill as blackmagic probe ===

Instructions in [https://forum.pine64.org/showthread.php?tid=8816&pid=57095#pid57095 forum post] or [https://gist.github.com/darnel/dac1370d057e176386ca4026418abc2b gist] (mac os)

== Manual / Articles ==

* [https://github.com/najnesnaj/pinetime-zephyr Beginner manual explained how you to programs and install zephyr on PineTime Dev Kit, big thanks to najnesnaj :-)]

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

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

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

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

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

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

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

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

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

== Development efforts ==

{| class="wikitable"
!
! Project Homepage
! Project Source
! PineTime Implementations

|-
! FreeRTOS
|https://www.freertos.org
| https://sourceforge.net/projects/freertos/
| [https://github.com/JF002/Pinetime JF002/Pinetime]
[https://github.com/kaythe/pinetime-os kaythe/pinetime-os]

|-
! Zephyr
| https://www.zephyrproject.org
| https://github.com/zephyrproject-rtos/zephyr
| [https://github.com/najnesnaj/pinetime-zephyr najnesnaj/pinetime-zephyr]
[https://github.com/SuperPrower/pinetime_zephyr_sample_fw SuperPrower/pinetime_zephyr_sample_fw]

|-
! mynewt
| https://mynewt.apache.org/about/
| https://github.com/apache/mynewt-core
| [https://github.com/lupyuen/pinetime-rust-mynewt lupyuen/pinetime-rust-mynewt]

|-
! MbedOS
| https://os.mbed.com
| https://github.com/ARMmbed/mbed-os
| [https://github.com/sethitow/awesome-pinetime sethitow/mbed-pinetime]

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

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

|-
! MicroPython
|
|
| [https://github.com/daniel-thompson/wasp-os daniel-thompson/wasp-os]
|-
|}

== Datasheets and Schematics ==

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

=== Component Datasheets ===
* NORDIC SoC information:
** [http://files.pine64.org/doc/datasheet/pinetime/nRF52832%20product%20brief.pdf NORDIC nRF52832 Product Brief]
* PMU (Power Management Unit) information:
** [http://files.pine64.org/doc/datasheet/pinetime/SGM40561.pdf SGMicro SGM40561 Single Cell Charger Datasheet]
** [http://files.pine64.org/doc/datasheet/pinetime/SGMICRO-SGM2036.pdf SGMicro SGM2036 3.3V Low Power Low Dropout RF Linear Regulator Datasheet]
* SPI Flash information:
** [http://files.pine64.org/doc/datasheet/pinetime/MX25L6433F,%203V,%2064Mb,%20v1.6.pdf Macronix 64Mb(8MB) SPI NOR Flash]
** [http://files.pine64.org/doc/datasheet/pinetime/MX25L12835F,%203V,%20128Mb,%20v1.6.pdf Macronix 128Mb(16MB) SPI NOR Flash]
* LCD Panel:
** [http://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:
** [http://files.pine64.org/doc/datasheet/pinetime/PineTime%20Touch%20Panel.jpg Touchpad Specification for PineTimel]
** [http://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/5/51/CST816S%E6%95%B0%E6%8D%AE%E6%89%8B%E5%86%8CV1.1.en.pdf English Translation]
* Sensor:
** [http://files.pine64.org/doc/datasheet/pinetime/BST-BMA421-FL000.pdf BOSCH BMA421 Triaxial VAcceleration Sensor Product Brief]
** [http://files.pine64.org/doc/datasheet/pinetime/HRS3300%20Heart%20Rate%20Sensor.pdf TianYiHeXin HRS3300 PPG Heart Rate Sensor Data Sheet]

= Community =
* [https://forum.pine64.org/forumdisplay.php?fid=134 PineTime forum]
* [https://riot.im/app/#/room/#pinetime64:matrix.org Matrix Channel] (No login required to read)
* IRC: Server us.pine64.xyz. Type /list to see all channels
* [https://t.me/pinetime Telegram group]
* [https://discordapp.com/invite/DgB7kzr Discord server invite link]

PineTime FAQ

2020-01-15T05:37:10Z

Darnel: Link to this comment does not makes sense to me