Differences

This shows you the differences between two versions of the page.

--- manual:chapter4:usb [2019/11/02 09:37]
jojo1973 created
+++ manual:chapter4:usb [2021/07/28 08:52]
claudio [Backup and Restore]
@@ Line 1: / Line 1: @@
-===== USB connectivity =====
+===== USB operations =====
-newRPL provides full USB support between calculator and PC: the calculator acts as an HID device, therefore the procedure of [[manual:chapter1:usbcomms|first-time setup]] is minimal, practically non-existent is some cases. The language implements a number of commands to handle file transfer between calculator and PC, as well as firmware update, as easy as possible.
+**newRPL** provides full USB support between calculator and PC: the calculator acts as an HID device, therefore the procedure of [[manual:chapter1:usbcomms|first-time setup]] is minimal, practically non-existent is some cases. The language implements a number of commands to handle file transfer between calculator and PC, as well as firmware update, as easy as possible.
 ==== Connection ====
@@ Line 13: / Line 13: @@
 In case of disconnection the status bar will show **[ Click to reconnect ]** allowing a quick reconnection of the calculator.
+On the models that support USB power, the battery indicator will turn gray when the USB cable is plugged, to indicate it's drawing power from the USB port.
 ==== Data Transfer ====
-Once the communication channel is set up, to transfer an object to **newRPL Desktop** use the command ''USBSEND'': if the transfer is successful, the object will appear on **newRPL Desktop** screen.
+Once the communication channel is set up, to transfer an object to **newRPL Desktop** use the command ''[[manual:chapter6:usb:cmd_usbsend|USBSEND]]'': if the transfer is successful, the object will appear on **newRPL Desktop** screen.
-Since ''USBSEND'' returns ''1'' in case of success and ''0'' otherwise, this snippet of code is the preferred way to ensure that the object on level 1 is transferred.
+Since ''[[manual:chapter6:usb:cmd_usbsend|USBSEND]]'' returns ''1'' in case of success and ''0'' otherwise, this snippet of code is the preferred way to ensure that the object on level 1 is transferred.
 <code>
@@ Line 29: / Line 30: @@
 </code>
-The receiving calculator will immediately ''[[manual:chapter6:operators:cmd_ovr_xeq|XEQ]]''%%'%%te the object after the trasfer has completed __provided no other program is currently in execution__. In that case ''[[manual:chapter6:operators:cmd_ovr_xeq|XEQ]]''%%'%%tion will be post-poned after the first program has terminated.
+The receiving calculator will immediately ''[[manual:chapter6:operators:cmd_ovr_xeq|XEQ]]''%%'%%te the object after the transfer has completed __provided no other program is currently in execution__. In that case ''[[manual:chapter6:operators:cmd_ovr_xeq|XEQ]]''%%'%%tion will be postponed after the first program has terminated.
-The command ''USBRECV'' is used to manually receive an object (avoiding to run it if it's a program): it accepts a time-out in seconds, after which the transfer is aborted. Alternatively, setting flag [[manual:appendix:flags#flag-47|-47]] will achieve the same effect. In any case, if there's data waiting to be received a **RX** indicator will be displayed in the status area; since transfer are not queued if there's an object waiting to be received, any other ''USBSEND'' command issued by the source calculator will fail.
+The following program puts the above concepts together into action.
+<code>
+« @@ Write a program that sends PONG back to us...
+  « "PING"
+    "PONG"
+    DO
+      DUP
+    UNTIL
+      USBSEND
+    END
+    DROP
+  »
+  @@ ...and send the program to the other side
+  DO
+    DUP
+  UNTIL
+    USBSEND
+  END
+  DROP
+»
+</code>
+The command ''[[manual:chapter6:usb:cmd_usbrecv|USBRECV]]'' is used to manually receive an object (avoiding to run it if it's a program): it accepts a time-out in seconds, after which the transfer is aborted. Alternatively, setting flag [[manual:appendix:flags#flag-47|-47]] will achieve the same effect. In any case, if there's data waiting to be received a **RX** indicator will be displayed in the status area; since transfer are not queued if there's an object waiting to be received, any other ''[[manual:chapter6:usb:cmd_usbsend|USBSEND]]'' command issued by the source calculator will fail.
+When flag [[manual:appendix:flags#flag-47|-47]] is set an object can be received and automatically ''[[manual:chapter6:operators:cmd_ovr_xeq|XEQ]]''%%'%%ted using the ''[[manual:chapter6:usb:cmd_usbautorcv|USBAUTORCV]]'' command.
+==== Backup and Restore ====
+**newRPL** allows archiving and restoring of memory across the USB wire. Simply:
+  - run ''[[manual:chapter6:usb:cmd_usbrestore|USBRESTORE]]'' on the receiving calculator: the command needs a time-out in seconds, so <code>30 USBRESTORE</code> will usually suffice;
+  - run ''[[manual:chapter6:usb:cmd_usbarchive|USBARCHIVE]]'' on the source machine.
+The backup format is totally compatible with ''[[manual:chapter6:sdcard:cmd_sdarchive|SDARCHIVE]]''/''[[manual:chapter6:sdcard:cmd_sdarchive|SDRESTORE]]'' but bear in mind that different platforms support different amounts of RAM: it's always possible to transfer backups across different platforms, provided they fit in the available RAM.
+^ Platform  ^ RAM  ^
+| HP39GS / HP39g+  | 256 KiB  |
+| HP40GS  | 256 KiB  |
+| HP50g  | 512 KiB  |
+| Prime G1  | 32 MiB  |
+| newRPL Desktop  | 10 MiB  |
+The above procedure will send the backup file to the other end of the wire. **newRPL Desktop** also provides options to directly execute ''[[manual:chapter6:usb:cmd_usbarchive|USBARCHIVE]]'' on the remote calculator and save the file to disk, without affecting the simulated calculator, and also to open a file from disk, and run a ''[[manual:chapter6:usb:cmd_usbrestore|USBRESTORE]]'' directly on the remote machine. This is useful to backup your connected calculator.
+==== USB Operations ====
+^ Command  ^ Purpose  ^ Example  ^
+| ''[[manual:chapter6:usb:cmd_usbsend|USBSEND]]''  | Send an object across USB wire  | '' « "CONNECTED!" » [[manual:chapter6:usb:cmd_usbsend|USBSEND]]''  |
+| ''[[manual:chapter6:usb:cmd_usbrecv|USBRECV]]''  | Manually receive an object across USB wire  | ''5 [[manual:chapter6:usb:cmd_usbrecv|USBRECV]]''  |
+| ''[[manual:chapter6:usb:cmd_usbautorcv|USBAUTORCV]]''  | Manually receive an object across USB wire and ''[[manual:chapter6:operators:cmd_ovr_xeq|XEQ]]''%%'%%te it  | ''[[manual:chapter6:usb:cmd_usbautorcv|USBAUTORCV]]''  |
+| ''[[manual:chapter6:usb:cmd_usbarchive|USBARCHIVE]]''  | Send a complete backup across USB wire  | ''[[manual:chapter6:usb:cmd_usbarchive|USBARCHIVE]]''  |
+| ''[[manual:chapter6:usb:cmd_usbrestore|USBRESTORE]]''  | Receive a backup across USB wire and restore it  | ''30 [[manual:chapter6:usb:cmd_usbrestore|USBRESTORE]]'' |
+| ''[[manual:chapter6:usb:cmd_usbstatus|USBSTATUS]]''  | Display status of USB connection  | ''[[manual:chapter6:usb:cmd_usbstatus|USBSTATUS]]''  |
+| ''[[manual:chapter6:usb:cmd_usbon|USBON]]''  | Enable the USB driver  | ''[[manual:chapter6:usb:cmd_usbon|USBON]]''  |
+| ''[[manual:chapter6:usb:cmd_usboff|USBOFF]]''  | Disable the USB driver | ''[[manual:chapter6:usb:cmd_usboff|USBOFF]]''  |