The other half

Revision as of 13:46, 22 September 2014

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 :)