===== 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.

==== Connection ====

  * Start **newRPL Desktop** and plug in the calculator to the PC;
  * from the __Hardware__ menu choose __USB Connections...__
  * under the menu will appear a status bar with a button labeled **[ Select a USB device ]**;
  * after clicking it, a list of devices connected to the PC will be shown: selecting the calculator and clicking **Ok** will complete the connection;
  * if everything went ok, the status bar will change accordingly;

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 ''[[manual:chapter6:usb:cmd_usbsend|USBSEND]]'': if the transfer is successful, the object will appear on **newRPL Desktop** screen.

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>
« DO
    DUP
  UNTIL
    USBSEND
  END
  DROP
»
</code>

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 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]]''  |