Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

DOCS-1113: Add clarification for running code remotely to client SDK Run Code page #1819

Merged
merged 11 commits into from
Sep 21, 2023
Merged

DOCS-1113: Add clarification for running code remotely to client SDK Run Code page #1819

Changes from 2 commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
c42c62c
Add clarification for running code remotely
sguequierre Sep 13, 2023
934ec09
Apply suggestions from code review
sguequierre Sep 14, 2023
9209404
Apply suggestions from code review
sguequierre Sep 14, 2023
22d3d84
Apply suggestions from code review
sguequierre Sep 14, 2023
b0b554c
Apply suggestions from code review
sguequierre Sep 14, 2023
a590261
Apply suggestions from code review
sguequierre Sep 14, 2023
e3bb471
Apply suggestions from code review
sguequierre Sep 14, 2023
36c579a
Apply suggestions from code review
sguequierre Sep 21, 2023
d801921
Update run.md use case
sguequierre Sep 21, 2023
0467b87
Apply suggestions from code review
sguequierre Sep 21, 2023
0110904
Update run.md
sguequierre Sep 21, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 18 additions & 18 deletions docs/program/run.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,13 +10,27 @@ tags: ["client", "sdk", "application", "sdk", "fleet", "program"]

After saving your [code sample](/program/#hello-world-the-code-sample-tab) and adding control logic with [Viam's SDKs](/program/apis/), run your program to control your Viam-connected robot.

## Run Code Remotely
### Authentication

You must reference a robot's location secret to authenticate yourself to the robot.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think a user would know what they are supposed to do to "reference a robot's location secret", maybe include or add would be better?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh I see now you were just movign this up... We can fix it separetely

However, the app hides the robot location secret from the sample by default for your security.

To copy the robot location secret, select **Include Secret** on the **Code sample** tab of your robot's page on the [Viam app](https://app.viam.com).
Paste it into your SDK code as directed by the code sample.

As long as you are connecting to your robot through an external signaling address, you can remotely control your robot without editing the app-generated connection code in your SDK program beyond including the necessary [authentication credentials](#authentication).
You must also include the robot's remote address, like `12345.somerobot-main.viam.cloud`, as an external or public address to connect to your robot.
The code sample should include this address at default.
sguequierre marked this conversation as resolved.
Show resolved Hide resolved
You can find it at the top of the robot's **Control** tab.

{{% snippet "secret-share.md" %}}

## Run Code Remotely

Do this by running a command to execute the program in the terminal of a machine with the appropriate programming language and Viam SDK installed.
Most of the time, as long as both you and your robot are connected to the internet, you will want to upload code to your robot remotely.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This doesn't make sense to have in a section that has the heading "run code remotely" because you're not describing that - you're describing moving the code to the robot and running it there instead.

Copy link
Collaborator Author

@sguequierre sguequierre Sep 14, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmmm-- this is the ask itself. And I can change the heading but you are running code remotely, like remotely from the computer where the robot is located, then it "moves" the code to the robot. Vs on-robot, you are on the same computer. I believe remote is a fairly standard term for this but I am slightly head-scratched by this as well so I can see why it's confusing. What would you think about Run Code Remotely from the Robot? @npentrel Or do you have any other suggestions?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

But if you are running the code from the robot you are by definition not remote? I think this conflates both concepts. Here's my understanding with my guardian robot as the example. I can:

  1. Run the code that makes it move and follow my dog from my macbook. Then I am running the code remotely. The python code does not get "moved" to the robot. A client session is created and the code running on my macbook will send instructions to the viam-server instance. If the connection drops because my mac loses wifi, the robot stops moving because the code is not actually on the robot now, it was just receiving the commands resulting from the code.
  2. Run the code locally on the robot. Then I am putting the python file for my robot on the raspberry pi that is the heart of the robot. This is what I actually do and then I have the script automatically start when viam-server is running.

Now, it occurs to me that it could also be that by "remote" we might mean not on the same WAN/LAN. I'm not sure that's clear. But also then - no code is uploaded.

^ Does this make it clearer? Explaining it with an example may help the reader's understanding here

Copy link
Collaborator Author

@sguequierre sguequierre Sep 21, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, that is super helpful, thank you @npentrel!! I was confused thinking about how it worked/didn't realize "uploading code to the robot" was inaccurate. Will edit to have the use case with the macbook to make that more clear.

sguequierre marked this conversation as resolved.
Show resolved Hide resolved
The advantage of this method is that your robot and your computer do not have to be connected to the same WAN/LAN to issue control commands, as your robot receives operation requests from your client program over the cloud.
sguequierre marked this conversation as resolved.
Show resolved Hide resolved

sguequierre marked this conversation as resolved.
Show resolved Hide resolved
For example:
As long as you are connecting to your robot through an external signaling address, you can remotely control your robot from anywhere in the world.
sguequierre marked this conversation as resolved.
Show resolved Hide resolved
After editing your code to include your robot's [authentication credentials](#authentication), run a command to execute the program in the terminal of a machine with the appropriate programming language and Viam SDK installed:

{{< tabs >}}
{{% tab name="Python" %}}
Expand Down Expand Up @@ -54,20 +68,6 @@ flutter run <DART_FILE>

This is useful because as long as that computer is able to establish a network connection with the robot's computer, your control logic will be executed on the robot.

### Authentication

You must reference a robot's location secret to authenticate yourself to the robot.
However, the app hides the robot location secret from the sample by default for your security.

To copy the robot location secret, select **Include Secret** on the **Code sample** tab of your robot's page on the [Viam app](https://app.viam.com).
Paste it into your SDK code as directed by the code sample.

You must also include the robot's remote address, like `12345.somerobot-main.viam.cloud`, as an external or public address to connect to your robot.
The code sample should include this address at default.
You can find it at the top of the robot's **Control** tab.

{{% snippet "secret-share.md" %}}

## Run Code On-Robot

{{< alert title="Info" color="info" >}}
Expand Down
Loading