The other half

Jolla The OtherHalf information (WIP)

Official documentation

• The official development kit documentation from Jolla: Jolla TOH DevKit, contains:
  • Pin layout
  • Hardware functional descriptions
  • 3D models (cover and phone backside)
  • SW functional description

Quirks and good to know stuff

• 5V VIN charging pin has a 5,5V zener diode connection to ground to protect from overvoltage
  • So solar/wireless charger hackers, over 5,5V most likely will result in power leaking via the zener instead of charging fully.
• Add more here ...

The unofficial EEPROM configuration functionality

As an unofficial feature, the toh kernel driver checks for existance of a EEPROM memory in I2C address 0x50 (that is default start address of AT24 compatible EEPROM memory chips), and export few pieces of configuration information into sysfs based on the contents of the EEPROM (if one was found). The history of this feature is that it was implemented before Jolla decided to focus on NFC tag based cover identification, but since it was felt that it could still serve purpose for hardware hackers, or as an additional configuration tool, it was left into the Jolla kernel for people to use.

So it is not an officially supported feature, but it's not going away either :)

The data that kernel looks for in the EEPROM looks as follows:

struct toh_eeprom_entry {
	char name[12];
	u16 size;	/* entry size in 8-bit bytes */
	u8 offset;	/* address offset of the data */
};

struct toh_eeprom_entry toh_eeprom[] = {
	{ TOH_EEPROM_VENDOR, 2, 0 },
	{ TOH_EEPROM_PRODUCT, 2, 2 },
	{ TOH_EEPROM_REV, 1, 4 },
	{ TOH_EEPROM_EEPROM_SIZE, 2, 5 },
	{ TOH_EEPROM_CFG_ADDR, 2, 7 },
	{ TOH_EEPROM_CFG_SIZE, 2, 9 },
	{ TOH_EEPROM_UDATA_ADDR, 2, 11 },
	{ TOH_EEPROM_UDATA_SIZE, 2, 13 },
};

If an EEPROM is found, there will be entries added to sysfs:

/sys/devices/platform/toh-core.0/vendor       # Vendor ID
/sys/devices/platform/toh-core.0/product      # Product ID
/sys/devices/platform/toh-core.0/rev          # Product revision
/sys/devices/platform/toh-core.0/eeprom_size  # Size of this eeprom
/sys/devices/platform/toh-core.0/cfg_addr     # Start address of configuration string
/sys/devices/platform/toh-core.0/cfg_size     # Length of configuration string
/sys/devices/platform/toh-core.0/udata_addr   # Start address of user data
/sys/devices/platform/toh-core.0/udata_size   # Length of user data string
/sys/devices/platform/toh-core.0/config_data  # String read from cfg_addr limited to first "\0" or to cfg_size

# And you ask why no user_data entry.. well, it was never implemented, sorry.

This EEPROM configuration information can be used to create automatic launching of SW services for that uniquely identifiable device. The usual thing is that you set up a udev rule to launch something when the right vendor/device id pair pops up in sysfs. In more complex case you could have some configuration string containing a things like URL to launch in browser, or some individual cover based settings (that you can modify and they stick).

EEPROM Vendor and Product ID table

To make the different TOH implementations uniquely identifiable, it is recommended to add your Vendor ID in the below list, so that it would not clash with existing Other Half implementations out there. (Don't worry, even though "Vendor ID" sounds very official, it's just a number... Fast get to choose first :)

Vendors

VID	Owner
0x4b4c	kimmoli
0x1989	dirkvl
0x2931	Jolla Oy
0x4a44	jrgdre

Devices

VID	PID	Owner	Product
0x4b4c	0x0002	kimmoli	Toholed
0x4b4c	0x0003	kimmoli	Tohiri
0x4b4c	0x0004	kimmoli	Toheink
0x4b4c	0x0005	kimmoli	Letoh
0x4b4c	0x0006	kimmoli	Tohuart
0x4b4c	0x0007	kimmoli	Tohmm
0x4b4c	0x0008	kimmoli	Tohnfc
0x4b4c	0x0009	kimmoli	FMTOH
0x1989	0x0002	dirkvl	diptoh
0x1989	0x0003	dirkvl	tohkbd (rev2)
0x1989	0x0004	dirkvl	breadboardtoh

Use the I2CTool to write EEPROM

To program an EEPROM on TOH, which has microswitch-dimple, you need to run this tool as root.

Otherwise you can start it after installation from the launcher icon.

Detailed users-guide can be downloaded from kimmoli github

1. Install i2ctool from jolla store
2. Attach TOH with an EEPROM to your phone
3. To enable EEPROM functions, unbind EEPROM from toh-core by giving following command on terminal as root
   echo toh-core.0 > /sys/bus/platform/drivers/toh-core/unbind
4. Start i2ctool from launcher icon
5. Click enable Vdd button, power indicator should show now ON
6. Click TOH EEPROM button
7. View with lots of FFFF should appear. If EEPROM was not found, tool gives you error message.
8. Click on each field to edit value. All values are in HEX (for details see above)
   1. Vendor ID: Your vendor ID assigned above
   2. Product ID: Your product ID assigned above
   3. Revision: As you wish
   4. EEPROM Size: for 2k EEPROM, use 100
   5. CFG Addr: 40
   6. CFG Size: 10 (TBD)
   7. UDATA Addr: 80
   8. UDATA Size: 0
9. Double check values
10. Click Write button
11. Optional: You can also edit CFG data by selection in pulldown menu
12. Swipe back to main menu
13. Click again TOH EEPROM button, to manually verify that the values have been written to the EEPROM (This action re-reads them)
14. Swipe back to main menu
15. Click disable Vdd button
16. Close i2ctool

Using udev rules to start daemon

By example of toholed;

This file is installed in spec with following line under %files tag:

%config /etc/udev/rules.d/95-%{name}.rules

After installing, udev rules may need to be reloaded, just to make sure, add this under %post tag:

udevadm control --reload

It triggers on KERNEL event of toh-core.0 ACTION add with matching vendor and product ATTRibutes, and starts harbour-toholed -binary as systemd service.

When KERNEL event of toh-core.0 ACTION remove is triggered it will stop the systemd service. Actually all services started with such rules are stopped (this makes no harm).

95-harbour-toholed.rules

# Toholed udev rules. Start daemon on insert, stop on remove
# TOH_VID = 0x4b4c, TOH_PID = 0x0002
#
KERNEL=="toh-core.0", ATTR{vendor}=="19276", ATTR{product}=="2", ACTION=="add", RUN+="/bin/systemctl start harbour-toholed"
KERNEL=="toh-core.0", ACTION=="remove", RUN+="/bin/systemctl stop harbour-toholed"

To start deamon during installation, i added following to %post to manually grep and check vendor and product id's (there might be easier way but when doing this i couldn't find such) :

if [ -e /sys/devices/platform/toh-core.0/vendor ]; then
 if grep -q 19276 /sys/devices/platform/toh-core.0/vendor ; then
  if grep -q 2 /sys/devices/platform/toh-core.0/product ; then
   systemctl start %{name}.service
  fi
 fi
fi