databankr/README

Databankr: store arbitrary data inside Casio Databank/Telememo watches
----------------------------------------------------------------------
This is a Python utility program that allows you to encode arbitrary pieces
of information into the format that could be entered into Casio watches with
the databank/telememo function support, as well as retrieve and decode this
information later. It supports both raw and hexadecimal data, as well as both
file and standard input/output.

== Usage ==

The program can be run like this (as always, use -h flag to see live help):

python3 databankr.py [enc/dec] [-t TYPE] [-i INPUT_FILE] [-o OUTPUT_FILE]
                     [-c CONFIG] [-m MODULE] [-l EXPECTED_LENGTH]

where the mode (enc/dec) parameter is mandatory, and the optional ones are:

* -t: data type to be encoded or decoded (bin or hex, bin by default,
      which means raw data)
* -i: source input file path (default "-", which means stdin)
* -o: result output file path (default "-", which means stdout)
* -c: configuration file path (default "config.json" in the current dir)
* -m: module configuration code according to your watch (default 2515-lat)
* -l: expected decoded data length in bytes (default is 0 - no limits)

In the encoding mode, the program outputs (to a file or the standard output)
a set of double newline separated records that you need to enter into the
databank/telememo function of your watch. Note that the amount of characters
is fixed for every model, so if the record name/number contains less of them,
then you must enter whitespaces into the rest. The input to the encoding mode
can also be a file or the standard input, and the data type flag (-t) defines
whether this is a raw binary file or a hexadecimal string.

In the decoding mode, the program expects a set of double newline separated
databank/telememo records from a file or the standard input and outputs the
reconstructed data into a file or the standard output according to the data
type flag. By default, the output is bit-aligned with the number of records
and the amount of bits held by each of them, so the excess data are filled
with null bytes. If you know the exact byte count of the source data, you can
pass the -l flag to strip the restored information to the desired length.

If you choose to enter the data manually via the standard input, press Ctrl+D
when done. This works in both modes.

Keep in mind that the records are case-sensitive: you must only enter the
letters in exactly the same case it has been specified in the configuration
section for the module of your choice. Most of the time, it will be upper case
for the name parts of the records.

== Configuration format ==

The basic configuration file is shipped with Databankr and is suitable for
several popular databank-enabled Casio models, but you can always extend it
to support other ones if you know the structure of their records. The file is
a normal JSON object where the keys are module identifiers (not necessarily
matching the only module it can work on), and the values are module config
objects. Each such object contains the following fields:

* description: a human-readable module description displayed by Databankr
* namelen: the name field length in a databank record (in characters)
* numberlen: the number field length in a databank record (in characters)
* alpha: the entire character set that can be entered into a name field
* digit: the entire character set that can be entered into a number field
* index: a subset of the "alpha" charset sorted alphabetically that's used
         for record indexing; its length must be equal to the total amount
         of records in the watch

The namelen and numberlen fields are integers, all others are strings. The
"index" field is necessary because all Databank/Telememo-enabled Casio watches
utilize automatic sorting, so, to preserve the data order, the first character
in the name part of the record actually is used to index the records and not
store the data payload itself.

== FAQ ==

- How and why this was invented?

Databankr started in early 2023 as a JavaScript library with a different name,
Telememer, that only catered to Casios with 2757 and 5574 modules (like AW-80,
AMW-870 and so on). It was created as an attempt to turn the Telememo function
of these watches into a kind of universal storage for arbitrary binary data,
as such a storage is pretty much unhackable and only accessible to those who
physically uses the watch. Besides, a phone or even a paper notebook are much
more likely to be stolen, searched or confiscated than a cheap wristwatch from
Casio. Then, in mid-2024, Databankr was created in its current form of a CLI
application written in Python 3, supporting several different Casio modules
out of the box.

- How much data can we store this way?

The overall formula of bits per record looks like this:

bits = |number_len * log2(digits)| + |(name_len - 1) * log2(chars)|,

where "digits" is how many different digits we can enter into the number part,
"chars" is how many different characters we can enter into the name part, and
"number_len" and "name_len" are the length of the number and name fields
respectively. Then we can multiply this number by the amount of records and it
will be the total storage. For example, with the default "2515-lat" module
configuration (which corresponds to a Casio DB-36/DB-360/DB-380 watch set to 
English or Dutch language), we can store 95 bits per record which translates 
to 2850 bits or 356 bytes of information in the entire databank.

- What kind of information can I store in such limited space?

If you happen to own an old and more advanced Casio Databank model (with 50,
100 or even 150 records), you'll find even more possibilities (after creating
your own configuration section for that model, of course: note that the main
limit in this case will be the amount of characters in the alphabet). However,
even 2850 bits are still over 2048, which means you can store several 
cryptographic keys, important URLs and passwords (in an encrypted fashion) or
other information that you don't need to glance at but need to be able to 
recover if you're only storing it on this particular Casio. Besides databank 
capacity, the only real tradeoff is your own readiness to manually enter the 
records into the watch and then retype them into the program (or a file) 
whenever you need to recover the information.

- What happens if I enter more data that can be stored on encoding?

It will be truncated prior to converting to records. Only one record set is
supported at the moment.

- Which modules are supported as of now?

Currently, Databankr comes with the configurations for the following modules:

* 675: Casio modules 675 and 1475 (e.g. DB-520, DB-810) - up to 42 records
* 2747: Casio modules 2747 and 5574 (AW-80, AMW-870, HDC-600 etc)
* 2515-lat: Casio modules 2515 and 3227, basic Latin characters
* 2515-cyr: Casio modules 2515 and 3227, Cyrillic characters
* 2515-por: Casio modules 2515 and 3227, Portuguese characters 

Even though the program itself is considered complete, the configuration list
is expected to grow in the future. Of course, everyone is encouraged to append
their own configurations according to the "Configuration format" section.

Note that for the 675/1475 modules, the @ character actually refers to the 
"hourglass" symbol that comes last in the character table.

== Credits ==

Created by Luxferre in 2024. Released into public domain with no warranties.