From 63038e62107f6bb4425bc0ff0be1c1db9b5a91ee Mon Sep 17 00:00:00 2001 From: Jonathan Cross Date: Wed, 6 Dec 2017 16:32:05 +0100 Subject: [PATCH] Improve / simplify documentation --- README.rst | 64 +++++--------------------------- docs/{USAGE.rst => EXAMPLES.rst} | 18 ++++----- docs/OPTIONS.rst | 63 +++++++++++++++++++++++++++++++ docs/README.rst | 5 +++ 4 files changed, 86 insertions(+), 64 deletions(-) rename docs/{USAGE.rst => EXAMPLES.rst} (93%) create mode 100644 docs/OPTIONS.rst create mode 100644 docs/README.rst diff --git a/README.rst b/README.rst index 06bde45..eae7fc8 100644 --- a/README.rst +++ b/README.rst @@ -7,7 +7,7 @@ python-trezor .. image:: https://badges.gitter.im/trezor/community.svg :target: https://gitter.im/trezor/community -Python library for communicating with TREZOR Hardware Wallet +Python library and commandline client for communicating with TREZOR Hardware Wallet See https://trezor.io for more information @@ -41,67 +41,21 @@ or build via ports: cd /usr/ports/security/py-trezor make install clean -Usage ------ -There is a command line tool called ``trezorctl`` which can perform various tasks. Use the following to learn about its commands: +Commandline client (trezorctl) +--------------------------- -.. code:: +The included ``trezorctl`` python script can perform various tasks such as changing setting in the Trezor, signing transactions, retrieving account info and addresses. See the `docs/ `_ sub folder for detailed examples and options. - trezorctl --help +NOTE: An older version of the ``trezorctl`` command is `available for Debian Stretch `_ (and comes pre-installed on `Tails OS `_). -or to learn options of a particular command: -.. code:: +Python Library +-------------- - trezorctl commands --help +You can use this python library to interact with a Bitcoin Trezor and use its capabilities in your application. +See examples here in the `tools/ `_ sub folder. -or visit `docs/USAGE.rst `_ page for more info. - -NOTE: The ``trezorctl`` command is `available for Debian Stretch `_ (and comes pre-installed on `Tails OS `_). - -To use the library in your application look at the following example. - -Example -------- - -also found in ``tools/helloworld.py`` - -.. code:: python - - #!/usr/bin/env python - - from trezorlib.client import TrezorClient - from trezorlib.transport_hid import HidTransport - - def main(): - # List all connected TREZORs on USB - devices = HidTransport.enumerate() - - # Check whether we found any - if len(devices) == 0: - print('No TREZOR found') - return - - # Use first connected device - transport = HidTransport(devices[0]) - - # Creates object for manipulating TREZOR - client = TrezorClient(transport) - - # Print out TREZOR's features and settings - print(client.features) - - # Get the first address of first BIP44 account - # (should be the same address as shown in wallet.trezor.io) - bip32_path = client.expand_path("44'/0'/0'/0/0") - address = client.get_address('Bitcoin', bip32_path) - print('Bitcoin address:', address) - - client.close() - - if __name__ == '__main__': - main() PIN Entering ------------ diff --git a/docs/USAGE.rst b/docs/EXAMPLES.rst similarity index 93% rename from docs/USAGE.rst rename to docs/EXAMPLES.rst index cc2728e..be85b23 100644 --- a/docs/USAGE.rst +++ b/docs/EXAMPLES.rst @@ -1,7 +1,7 @@ -Usage -===== +Examples demonstrating how to use trezorctl +=========================================== -Show help for all command: +Show all available `options `_: .. code:: @@ -15,8 +15,8 @@ Retrieve features, settings and coin types supported by your device: trezorctl get_features -Bitcoin -------- +Bitcoin examples +---------------- Get first receiving address of first account for Bitcoin (Legacy / non-SegWit): @@ -97,8 +97,8 @@ The signed transaction text can then be inspected in Electrum (`screenshot `_ or later. diff --git a/docs/OPTIONS.rst b/docs/OPTIONS.rst new file mode 100644 index 0000000..02ec1bf --- /dev/null +++ b/docs/OPTIONS.rst @@ -0,0 +1,63 @@ +Commandline options for trezorctl +================================= + +See `EXAMPLES.rst `_ for examples on how to use. + +Use the following command to see all options: + +.. code:: + + trezorctl --help + + +.. code:: + + Usage: trezorctl [OPTIONS] COMMAND [ARGS]... + + Options: + -t, --transport [usb|udp|pipe|bridge] + Select transport used for communication. + -p, --path TEXT Select device by transport-specific path. + -v, --verbose Show communication messages. + -j, --json Print result as JSON object + --help Show this message and exit. + + Commands: + backup_device Perform device seed backup. + change_pin Change new PIN or remove existing. + clear_session Clear session (remove cached PIN, passphrase,... + cosi_commit Ask device to commit to CoSi signing. + cosi_sign Ask device to sign using CoSi. + decrypt_keyvalue Decrypt value by given key and path. + decrypt_message Decrypt message. + disable_passphrase Disable passphrase. + enable_passphrase Enable passphrase. + encrypt_keyvalue Encrypt value by given key and path. + encrypt_message Encrypt message. + ethereum_get_address Get Ethereum address in hex encoding. + ethereum_sign_message Sign message with Ethereum address. + ethereum_sign_tx Sign (and optionally publish) Ethereum... + ethereum_verify_message Verify message signed with Ethereum address. + firmware_update Upload new firmware to device (must be in... + get_address Get address for specified path. + get_entropy Get example entropy. + get_features Retrieve device features and settings. + get_public_node Get public node of given path. + list List connected TREZOR devices. + list_coins List all supported coin types by the device. + load_device Load custom configuration to the device. + nem_get_address Get NEM address for specified path. + nem_sign_tx Sign (and optionally broadcast) NEM... + ping Send ping message. + recovery_device Start safe recovery workflow. + reset_device Perform device setup and generate new seed. + self_test Perform a self-test. + set_flags Set device flags. + set_homescreen Set new homescreen. + set_label Set new device label. + set_u2f_counter Set U2F counter. + sign_message Sign message using address of given path. + sign_tx Sign transaction. + verify_message Verify message. + version Show version of trezorctl/trezorlib. + wipe_device Reset device to factory defaults and remove... diff --git a/docs/README.rst b/docs/README.rst new file mode 100644 index 0000000..6153d74 --- /dev/null +++ b/docs/README.rst @@ -0,0 +1,5 @@ +Documentation for trezorctl commandline client +============================================== + +* `EXAMPLES.rst `_ - Examples demonstrating how to use trezorctl +* `OPTIONS.rst `_ - Commandline options for trezorctl