docs(readme): Update and clarify instructions and formatting

Author: davekrum

README.rst

@@ -3,62 +3,72 @@ PrusaConnect SDK for Printer
 
 Printer instance
 ----------------
-You can create a Printer instance using the constructor and passing `server` and `token` to it. These you can find in  `prusa_printer_settings.ini`.
+You can create a Printer instance using the constructor passing printer type,
+serial number and printer fingerprint to it. Serial number can be found on the printer label.
+For I3MK3 and SL1, printer fingerprint is a SHA256 HEX digest of the serial number.
 
 .. code:: python
 
     from prusa.connect.printer import Printer, const
 
+    SN = "Printer serial number"
+    FINGERPRINT = sha256(SN.encode()).hexdigest()
+    PRINTER_TYPE = const.PrinterType.I3MK3
+    printer = Printer(PRINTER_TYPE, SN, FINGERPRINT)
+
+For setting the connection you should call `set_connection` passing `server` and `token` to it. These you can find in the `prusa_printer_settings.ini` file. You can download it after printer registration from the Connect web by selecting your printer -> Settings -> LAN settings -> Download settings. If the printer has not been registered yet, refer to the Registration section below.
+
+.. code:: python
+
     SERVER = "https://connect.prusa3d.com"
-    SN = 'SERIAL_NUMBER_FROM_PRINTER'
-    FINGERPRINT = 'Printer fingerprint'
-    TOKEN = 'secret token from prusa_printer_settings.ini'
-    printer = Printer(const.PrinterType.I3MK3, SN, SERVER, TOKEN)
+    TOKEN = "Secret token from prusa_printer_settings.ini"
 
-    printer.loop()  # communication loop
+    printer.set_connection(SERVER, TOKEN)
 
-Or you can use `Printer.from_config()` method which reads these values from the ini file.
+    printer.loop()  # Communication loop
 
-.. code:: python
+Or you can use `printer.connection_from_config()` method which reads these values directly from the .ini file.
 
-    from prusa.connect.printer import Printer, const
+.. code:: python
 
-    SERVER = "https://connect.prusa3d.com"
-    SN = 'SERIAL_NUMBER_FROM_PRINTER'
-    printer = Printer.from_config("./prusa_printer_settings.ini",
-                                  const.PrinterType.I3MK3, SN)
+    printer.connection_from_config("./prusa_printer_settings.ini")
 
-    printer.loop()  # communication loop
+    printer.loop()  # Communication loop
 
 
 Registration
 ------------
-If the printer has not been registered yet, you need to use `Printer.register()` to get a temporary code. This code is then used in the **Add Printer** form in Connect Web. After the printer
-has been added to Connect, `Printer.get_token()` will return printer's persistent token.
+If the printer has not been registered yet, you need to use `Printer.register()` to get a temporary code. Enter this code in the **Add Printer** form in Connect Web. After the printer has been added to Connect, your Printer instance will automatically retrieve the code in the background.
 
 .. code:: python
 
     from time import sleep
     from prusa.connect.printer import Printer, const
 
     SERVER = "https://connect.prusa3d.com"
-    SN = 'SERIAL_NUMBER_FROM_PRINTER'
-    printer = Printer(const.PrinterType.I3MK3, SN, SERVER)
+    SN = "Printer serial number"
+    FINGERPRINT = "Printer fingerprint"
+    PRINTER_TYPE = const.PrinterType.I3MK3
+    printer = Printer(PRINTER_TYPE, SN, FINGERPRINT)
+
+    printer.set_connection(SERVER, None)
 
     tmp_code = printer.register()
     print(f"Use this code `{tmp_code}` in add printer form "
           f"{SERVER}/printers/overview?code={tmp_code}.")
 
-    token = None
-    while token is None:
-        token = printer.get_token(tmp_code)
+    while printer.token is None:
+        print("Waiting for the printer registration on the Connect web...")
         sleep(1)
 
-    print("Printer is registered with token %s" % token)
+    print(f"Printer is registered with token {printer.token}")
+
+Note: For I3MK3 the Add Printer form does not allow you manually enter the temporary code.
+You can use this url to add it directly: https://connect.prusa3d.com:443/add-printer/connect/{PRINTER_TYPE}/{tmp_code}
 
 Telemetry
 ---------
-Printer must send telemetry to connect at least each second. Because obtaining telemetry values might not be atomic, this must be done in a different thread than `Printer.loop`.
+Printer must send telemetry to Connect at least once per second. Because obtaining telemetry values might not be atomic, this must be done in a separate thread from `Printer.loop`.
 
 .. code:: python
 
@@ -67,29 +77,32 @@ Printer must send telemetry to connect at least each second. Because obtaining t
 
     ...
 
-    # start communication loop
+    # Start communication loop in a separate thread
     thread = Thread(target=printer.loop)
     thread.start()
 
-    # each second send telemetry to internal queue in the main-thread
+    # Send telemetry to the main thread queue once per second
     while True:
         printer.telemetry(const.State.READY, temp_nozzle=24.1, temp_bed=23.2)
         sleep(1)
 
-
 Events
 ------
-Events are a way to send information about the printer to Connect. They can be split into a few groups:
-
-    * **Command answers** - Response for Connect if the command was be ACCEPTED,
-      REJECTED, etc. These are handled by the SDK in `Printer.loop` method or in `Command.__call__` method.
-    * **State change** - indicating that the printer state has changed. This are sent
-      by `Printer.set_state` method.
-    * **FILE INFO** events which are created by `FileSystem` object.
-    * Alternatively you can inform Connect about other events like attaching/detaching of storage.
-      You can do this by calling `Printer.event_cb`.
-
-Examples for these groups follow below.
+Events are a way to send information about the printer to Connect.
+They can be grouped into several categories:
+
+**Command answers**
+Responses to Connect indicating whether a command was ACCEPTED, REJECTED, etc.
+These are handled by the SDK in the `Printer.loop` method or the `Command.__call__` method.
+**State changes**
+Indicate that the printer's state has changed. These are sent by the `Printer.set_state` method.
+**FILE INFO**
+Events created by the FileSystem object.
+**Other events**
+For example, informing Connect about storage being attached or detached.
+You can do this by calling `Printer.event_cb`.
+
+Examples of each category are provided below.
 
 Event callback
 --------------
@@ -101,15 +114,15 @@ You can inform Connect about some specific situation using events.
 
     ...
 
-    # start communication loop
+    # Start communication loop
     thread = Thread(target=printer.loop)
     thread.start()
 
     try:
         ...
     except Exception as err:
-        # send event to internal queue
-        printer.event_cb(const.Event.ATTENTION, const.Source.WUI,
+        # Send event to internal queue
+        printer.event_cb(const.Event.FAILED, const.Source.WUI,
                          reason=str(err))
 
 Printer state
@@ -122,11 +135,11 @@ Printer state
 
     ...
 
-    # start communication loop
+    # Start communication loop
     thread = Thread(target=printer.loop)
     thread.start()
 
-    # toggle the state each second
+    # Toggle the state each second
     while True:
         if printer.state == const.State.READY:
             printer.set_state(const.State.BUSY, const.Source.MARLIN)
@@ -168,26 +181,29 @@ a dictionary as a value.
     ...
 
     @printer.handler(const.Command.START_PRINT)
-    def start_print(args: List[str]):
+    def start_print(args: list[str]):
         """This handler will be called when START_PRINT command was sent to
            the printer."""
         printer.set_state(const.State.PRINTING, const.Source.CONNECT)
         print("Printing file: {args[0]}")
         ...
 
     @printer.handler(const.Command.STOP_PRINT)
-    def start_print(args: List[str]):
+    def start_print(args: list[str]):
         """This handler will be called when STOP_PRINT command was sent to
            the printer."""
         printer.set_state(const.State.READY, const.Source.CONNECT)
         print("Printing stopped")
         ...
 
-    # communication loop
+    # Communication loop
     thread = Thread(target=printer.loop)
     thread.start()
 
-    # try run command handler each 100 ms
+    # Set printer state to READY.
+    printer.set_state(const.State.READY, const.Source.CONNECT)
+
+    # Try run command handler each 100 ms
     while True:
         printer.command()
         sleep(0.1)