diff --git a/assets/js/howtos.js b/assets/js/howtos.js index c784766d422..0a6b41240c1 100644 --- a/assets/js/howtos.js +++ b/assets/js/howtos.js @@ -98,9 +98,9 @@ let refinementLists = [customRefinementList({ items: [ { label: "Data Management", value: "data" }, { label: "Machine Learning", value: "ml" }, - { label: "Core", value: "core" }, + { label: "Control hardware", value: "core" }, { label: "Fleet Management", value: "fleet" }, - { label: "Registry", value: "registry" }, + { label: "Integrate other hardware", value: "registry" }, { label: "Mobility", value: "mobility" }, ], }), diff --git a/assets/scss/_styles_project.scss b/assets/scss/_styles_project.scss index 54b8d8ca7bc..06e30a0254a 100644 --- a/assets/scss/_styles_project.scss +++ b/assets/scss/_styles_project.scss @@ -18,7 +18,7 @@ a.footnote-ref::after { /* START Adjust Heading sizes*/ .td-navbar { - background: black !important; + background-color: rgb(19,20,20) !important; } /* This ensures there is no padding added to the top logo bar */ @@ -35,7 +35,7 @@ a.footnote-ref::after { font-size: 0.833rem; line-height: 1.667em; letter-spacing: 0.1875rem; - padding: 5px 10px; + padding: 5px 8px; text-decoration: none; text-transform: uppercase; white-space: nowrap; @@ -44,6 +44,11 @@ a.footnote-ref::after { } } +.td-navbar .navbar-brand svg { + height: 16px; + margin: 0; +} + .td-navbar .nav-link { font-family: Space Mono, sans-serif; font-weight: 400; @@ -2556,3 +2561,118 @@ div.explanation > .explanationvisual > .gif { opacity: 0; transition: opacity 250ms ease-out; } + +// Top level nav START +nav { + display: flex; + flex-direction: column; +} + +.navcontainer { + min-width: 100%; + display: flex; +} + +.td-topbar-sections { + margin-right: auto !important; + margin-left: 0 !important; + line-height: unset !important; +} + +.td-topbar-sections > ul { + padding: 0; + padding-left: 1.25rem; + margin: 0.25rem 0 0 0; + border-left: 1px solid white; +} + +.td-topbar-sections > ul > li { + padding-right: 1.5rem; + display: inline-block; + text-transform: uppercase; + font-family: Roboto Mono Variable,Roboto Mono,ui-monospace,monospace; + font-size: .875rem; + line-height: 1.25rem; +} + +.td-topbar-sections > ul > li > a { + color: white; + padding-bottom: 8px; + padding-top: 8px; +} + +.td-topbar-sections > ul > li > a:hover { + text-decoration: none; +} + +.td-navbar { + min-height: 3.5rem; +} + +.navsectiontop.active-path { + border-bottom: 1px solid white; +} + +#navsearch { + min-width: 250.633px; +} + +span.section-overview { + display: none +} + +@media (min-width: 768px) { + .td-sidebar-nav__section ul.ul-1 { + padding-top: 0.5rem + } + + .ul-1 > li.nav-fold.hide-if-desktop { + display: none; + } + + .menu-toggle.open-on-desktop { + display: none; + } + + li.nav-fold.open-on-desktop > span > ul > li { + display: block !important; + } + + li.nav-fold.open-on-desktop.header-only > span > a { + text-transform: uppercase; + font-family: Space Mono,sans-serif; + color: #aaa; + margin-top: 1rem; + } + + li.nav-fold.open-on-desktop.header-only:first-child > span > a { + margin-top: 0.5rem; + } + + li.nav-fold.open-on-desktop.header-only * li { + text-transform: unset; + } + + li.open-on-desktop > span > ul.ul-2 { + padding-left: 0; + } + + li.open-on-desktop.header-only > span > ul.ul-3 { + padding-left: 0; + } + + span.section-overview-title { + display: none + } + + span.section-overview { + display: block + } + +} + +a.tree-root { + display: none; +} + +// Top level nav END diff --git a/docs/_index.md b/docs/_index.md index 3f400b11b22..777c00cc76a 100644 --- a/docs/_index.md +++ b/docs/_index.md @@ -5,6 +5,7 @@ description: "Viam integrates with hardware and software on any device. Use AI, weight: 1 no_list: true type: "docs" +layout: "landing" noToc: true hide_feedback: true sitemap: @@ -17,918 +18,3 @@ noedit: true date: "2024-09-17" updated: "2024-10-11" --- - -
-
-
-

Viam Documentation

-

- Viam integrates with hardware and software on any device. Use AI, machine learning, and more to make any machine smarter—for one machine to thousands. -

-
-
-
- -
-

How-to Guides

-
- -
-
-
-

Platform Reference →

- -
-
-
-
- Robot illustration -
-
-
- -
- -## Program any device - -To get started, install Viam on any device and create a configuration that describes connected hardware as {{< glossary_tooltip term_id="component" text="components" >}}. Then you can control your device and any attached physical hardware securely **from anywhere in the world**. Or from local networks. - -{{< tabs class="horizontalheaders program" navheader="Examples">}} -{{% tab name="Drive a base" %}} - -
- -{{< tabs >}} -{{% tab name="Python" %}} - -```python -async def moveInSquare(base): - for _ in range(4): - # Move forward 500mm at 500mm/s - await base.move_straight(velocity=500, distance=500) - # Spin 90 degrees at 100 degrees/s - await base.spin(velocity=100, angle=90) -``` - -{{% /tab %}} -{{% tab name="Go" %}} - -```go -func moveInSquare(ctx context.Context, base base.Base, logger logging.Logger) { - for i := 0; i < 4; i++ { - // Move forward 500mm at 500mm/s - base.MoveStraight(ctx, 600, 500.0, nil) - // Spin 90 degrees at 100 degrees/s - base.Spin(ctx, 90, 100.0, nil) - } -} -``` - -{{% /tab %}} -{{% tab name="TypeScript" %}} - -```ts -async function moveInSquare(baseClient: VIAM.BaseClient) { - for (let i = 0; i < 4; i++) { - // Move forward 500mm at 500mm/s - await baseClient.moveStraight(500, 500); - // Spin 90 degrees at 100 degrees/s - await baseClient.spin(90, 100); - } -} -``` - -{{% /tab %}} -{{% tab name="Flutter" %}} - -```dart -Future moveSquare() async { - for (var i=0; i<4; i++) { - // Move forward 500mm at 500mm/s - await base.moveStraight(500, 500); - // Spins the rover 90 degrees at 100 degrees/s - await base.spin(90, 100); - } -} -``` - -{{% /tab %}} -{{% tab name="C++" %}} - -```cpp -void move_in_square(std::shared_ptr base) { - for (int i = 0; i < 4; ++i) { - // Move forward 500mm at 500mm/s - base->move_straight(500, 500); - // Spins the rover 90 degrees at 100 degrees/s - base->spin(90, 100); - } -} -``` - -{{% /tab %}} -{{< /tabs >}} - -
-
- -You can use any robotic base with Viam. Configure it as a base component. Then you can drive it using the base API. - -[Drive a base →](/how-tos/drive-rover/) - -
-
- -{{}} - -
-
-
- -{{% /tab %}} -{{% tab name="Control motor" %}} - -
- -{{< tabs >}} -{{% tab name="Python" %}} - -```python -async def spin_motor(motor): - # Turn the motor at 35% power forwards - await motor.set_power(power=0.35) - # Let the motor spin for 3 seconds - time.sleep(3) - # Stop the motor - await motor.stop() -``` - -{{% /tab %}} -{{% tab name="Go" %}} - -```go -func spinMotor(ctx context.Context, motor motor.Motor, logger logging.Logger) { - // Turn the motor at 35% power forwards - err = motor.SetPower(context.Background(), 0.35, nil) - // Let the motor spin for 3 seconds - time.Sleep(3 * time.Second) - // Stop the motor - err = motor.Stop(context.Background(), nil) -} -``` - -{{% /tab %}} -{{% tab name="TypeScript" %}} - -```ts -async function spinMotor(motorClient: VIAM.MotorClient) { - // Turn the motor at 35% power forwards - await motorClient.setPower(0.35); - // Let the motor spin for 3 seconds - const sleep = (ms: number) => - new Promise((resolve) => setTimeout(resolve, ms)); - await sleep(3000); - // Stop the motor - await motorClient.stop(); -} -``` - -{{% /tab %}} -{{% tab name="Flutter" %}} - -```dart -Future spinMotor() async { - // Turn the motor at 35% power forwards - await motorClient.setPower(0.35); - // Let the motor spin for 3 seconds - await Future.delayed(Duration(seconds: 3)); - // Stop the motor - await motorClient.stop(); -} -``` - -{{% /tab %}} -{{% tab name="C++" %}} - -```cpp -void spin_motor(std::shared_ptr motor) { - // Turn the motor at 35% power forwards - motor->set_power(0.35); - // Let the motor spin for 3 seconds - sleep(3); - // Stop the motor - motor->stop(); -} -``` - -{{% /tab %}} -{{< /tabs >}} - -
-
- -You can use any motor with Viam. Configure it as a motor component. Then you can operate it using the motor API. - -[Control a motor →](/how-tos/control-motor/) - -
-
- -{{}} - -
-
-
-{{% /tab %}} -{{% tab name="Get sensor reading" %}} -
- -{{< tabs >}} -{{% tab name="Python" %}} - -```python -# Get the readings provided by the sensor. -co_2_monitor = Sensor.from_robot(machine, "co2-monitor") -co_2_monitor_return_value = await co_2_monitor.get_readings() -print(f"co2-monitor get_readings return value: {co_2_monitor_return_value}") -``` - -{{% /tab %}} -{{% tab name="Go" %}} - -```go -// Get the readings provided by the sensor. -co2Monitor, err := sensor.FromRobot(machine, "co2-monitor") -co2MonitorReturnValue, err := co2Monitor.Readings( - context.Background(), map[string]interface{}{}) -logger.Infof("co2-monitor return value: %+v", co2MonitorReturnValue) -``` - -{{% /tab %}} -{{% tab name="TypeScript" %}} - -```ts -// Get the readings provided by the sensor. -const co2MonitorClient = new VIAM.SensorClient(machine, "co2-monitor"); -const co2MonitorReturnValue = await co2MonitorClient.getReadings(); -console.log("co2-monitor return value:", co2MonitorReturnValue); -``` - -{{% /tab %}} -{{% tab name="Flutter" %}} - -```dart -// Get the readings provided by the sensor. -final co2Monitor = Sensor.fromRobot(client, "co2-monitor"); -var readings = await co2Monitor.readings(); -print(readings); -``` - -{{% /tab %}} -{{% tab name="C++" %}} - -```cpp -// Get the readings provided by the sensor. -auto co2monitor = machine->resource_by_name("co2-monitor"); -auto co2monitor_get_readings_return_value = co2monitor->get_readings(); -std::cout << "co2-monitor get_readings return value " << co2monitor_get_readings_return_value << "\n"; -``` - -{{% /tab %}} -{{< /tabs >}} - -
-
- -You can use any physical sensor or anything else that provides measurements with Viam. Configure it as a sensor component. Then you can get sensor readings using the sensor API. - -[Collect sensor data →](/how-tos/collect-sensor-data/) - -
-
-
-{{% /tab %}} -{{% tab name="Move an arm" %}} -
- -{{< tabs >}} -{{% tab name="Python" %}} - -```python -# Command a joint position move: move the forearm of the arm slightly up -cmd_joint_positions = JointPositions(values=[0, 0, -30.0, 0, 0, 0]) -await my_arm_component.move_to_joint_positions( - positions=cmd_joint_positions) - -# Generate a simple pose move +100mm in the +Z direction of the arm -cmd_arm_pose = await my_arm_component.get_end_position() -cmd_arm_pose.z += 100.0 -await my_arm_component.move_to_position(pose=cmd_arm_pose) -``` - -{{% /tab %}} -{{% tab name="Go" %}} - -```go -// Command a joint position move: move the forearm of the arm slightly up -cmdJointPositions := &armapi.JointPositions{Values: []float64{0.0, 0.0, -30.0, 0.0, 0.0, 0.0}} -err = myArmComponent.MoveToJointPositions(context.Background(), cmdJointPositions, nil) - -// Generate a simple pose move +100mm in the +Z direction of the arm -currentArmPose, err := myArmComponent.EndPosition(context.Background(), nil) -adjustedArmPoint := currentArmPose.Point() -adjustedArmPoint.Z += 100.0 -cmdArmPose := spatialmath.NewPose(adjustedArmPoint, currentArmPose.Orientation()) - -err = myArmComponent.MoveToPosition(context.Background(), cmdArmPose, nil) -``` - -{{% /tab %}} -{{< /tabs >}} - -
-
- -You can use any robotic arm with Viam. -Configure it as an arm component. Then you can move it using the arm API. - -[Move a robotic arm →](/how-tos/move-robot-arm/) - -
-
- -{{}} - -
-
-
-{{% /tab %}} -{{% tab name="Operate custom hardware" %}} -
- -{{< tabs >}} -{{% tab name="Python" %}} - -```python -my_button = Generic.from_robot(robot=machine, name="my_button") - -# Use a custom command to push the button 5 -command = {"cmd": "push_button", "button": 5} -result = await my_button.do_command(command) -``` - -{{% /tab %}} -{{% tab name="Go" %}} - -```go -myButton, err := generic.FromRobot(machine, "my_button") - -// Use a custom command to push the button 5 -command := map[string]interface{}{"cmd": "push_button", "button": 5} -result, err := myButton.DoCommand(context.Background(), command) -``` - -{{% /tab %}} -{{< /tabs >}} - -
-
- -Using the Viam Registry you can create _{{< glossary_tooltip term_id="resource" text="resources" >}}_ for additional hardware types or models and then deploy them to your machines. -You can use an existing component or service type or create generic resources. - -[Create a module →](/how-tos/hello-world-module/) - -
-
-
-{{% /tab %}} -{{< /tabs >}} - -
-
-
- -## Make your devices better and smarter - -

- Pick and choose from additional services. Make your devices understand their environment, interact with it, collect data, and more: -

-
- -{{< tabs class="horizontalheaders services" navheader="Services">}} -{{% tab name="Computer Vision" %}} - -
- -{{< tabs >}} -{{% tab name="Python" %}} - -```python -# Get image from camera stream on construction site -cam = Camera.from_robot(machine, "construction-site-cam") -img = await cam.get_image() - -# Use machine learning model to gather information from the image -hardhat_detector = VisionClient.from_robot(machine, "hardhat_detector") -detections = await hardhat_detector.get_detections(img) - -# Check whether a person is detected not wearing a hardhat -for d in detections: - if d.confidence > 0.8 and d.class_name == "NO-Hardhat": - print("Violation detected.") -``` - -{{% /tab %}} -{{% tab name="Go" %}} - -```go -// Get image from camera stream on construction site -myCamera, err := camera.FromRobot(machine, "construction-site-cam") -camStream, err := myCamera.Stream(context.Background()) -img, release, err := camStream.Next(context.Background()) -defer release() - -// Use machine learning model to gather information from the image -visService, err := vision.FromRobot(machine, "hardhat_detector") -detections, err := visService.Detections(context.Background(), img, nil) - -// Check whether a person is detected not wearing a hardhat -for i := 0; i < len(detections); i++ { - if (detection[i].confidence > 0.8) && (detection[i].class_name == "NO-Hardhat") { - logger.Info("Violation detected.") - } -} -``` - -{{% /tab %}} -{{< /tabs >}} - -
-
- -Computer vision enables your machine to use connected cameras to interpret the world around it. -With inferences about a machine's surroundings, you can program machines to act based on this input. - -[Try the vision service →](/tutorials/projects/helmet/) - -
-
- -{{}} - -
-
-
- -{{% /tab %}} -{{% tab name="Data Management" %}} - -
- -{{< tabs >}} -{{% tab name="Captured Data" %}} - -{{}} - -{{% /tab %}} -{{% tab name="Query Data" %}} - -```python -# Tag data from the my_camera component -my_filter = create_filter(component_name="my_camera") -tags = ["frontview", "trainingdata"] -res = await data_client.add_tags_to_binary_data_by_filter(tags, my_filter) - -# Query sensor data by filter -my_data = [] -my_filter = create_filter( - component_name="sensor-1", - start_time=Timestamp('2024-10-01 10:00:00', tz='US/Pacific'), - end_time=Timestamp('2024-10-12 18:00:00', tz='US/Pacific') -) -tabular_data, count, last = await data_client.tabular_data_by_filter( - my_filter, last=None) -``` - -{{% /tab %}} -{{< /tabs >}} - -
-
- -Sync sensor data, images, and any other binary or timeseries data from all your machines to the cloud. There, you can query and visualize it. - -Intermittent internet connectivity? Your data will sync whenever internet is available. - -[Learn about Data Management →](/services/data/) - -
-
-
-{{% /tab %}} -{{% tab name="Motion" %}} -
- -{{< tabs >}} -{{% tab name="Python" %}} - -```python -# Add a table obstacle to a WorldState -table_origin = Pose(x=-202.5, y=-546.5, z=-19.0) -table_dimensions = Vector3(x=635.0, y=1271.0, z=38.0) -table_object = Geometry(center=table_origin, - box=RectangularPrism(dims_mm=table_dimensions)) -obstacles_in_frame = GeometriesInFrame(reference_frame="world", - geometries=[table_object]) -world_state = WorldState(obstacles=[obstacles_in_frame]) - -# Destination pose to move to -dest_in_frame = PoseInFrame( - reference_frame="world", - pose=Pose(x=510.0, y=0.0, z=526.0, o_x=0.7, o_y=0.0, o_z=-0.7, theta=0.0)) - -# Move arm to destination pose -motion_service = MotionClient.from_robot(robot, "builtin") -await motion_service.move( - component_name=Arm.get_resource_name("myArm"), - destination=dest_in_frame, world_state=world_state) -``` - -{{% /tab %}} -{{% tab name="Go" %}} - -```go -// Add a table obstacle to a WorldState -obstacles := make([]spatialmath.Geometry, 0) -tableOrigin := spatialmath.NewPose( - r3.Vector{X: 0.0, Y: 0.0, Z: -10.0}, - &spatialmath.OrientationVectorDegrees{OX: 0.0, OY: 0.0, OZ: 1.0, Theta: 0.0}, -) -tableDimensions := r3.Vector{X: 2000.0, Y: 2000.0, Z: 20.0} -tableObj, err := spatialmath.NewBox(tableOrigin, tableDimensions, "table") -obstacles = append(obstacles, tableObj) -obstaclesInFrame := referenceframe.NewGeometriesInFrame(referenceframe.World, obstacles) -worldState, err := referenceframe.NewWorldState([]*referenceframe.GeometriesInFrame{obstaclesInFrame}, nil) - -// Destination pose to move to -destinationPose := spatialmath.NewPose( - r3.Vector{X: 510.0, Y: 0.0, Z: 526.0}, - &spatialmath.OrientationVectorDegrees{OX: 0.7071, OY: 0.0, OZ: -0.7071, Theta: 0.0}, -) -destPoseInFrame := referenceframe.NewPoseInFrame( - referenceframe.World, destinationPose) - -// Move arm to destination pose -motionService, err := motion.FromRobot(robot, "builtin") -_, err = motionService.Move(context.Background(), arm.Named("myArm"), destPoseInFrame, worldState, nil, nil) -``` - -{{% /tab %}} -{{< /tabs >}} - -
-
- -The motion service enables your machine to plan and move relative to itself, other machines, and the world. - -[Try the motion service →](/tutorials/services/plan-motion-with-arm-gripper/) - -
-
- -{{}} - -
-
-
-{{% /tab %}} -{{% tab name="Navigation" %}} -
- -{{< tabs >}} -{{% tab name="Python" %}} - -```python -my_nav = NavigationClient.from_robot(robot=robot, name="my_nav_service") - -# Create a new waypoint at the specified latitude and longitude -location = GeoPoint(latitude=40.76275, longitude=-73.96) - -# Add waypoint to the service's data storage -await my_nav.add_waypoint(point=location) - -my_nav = NavigationClient.from_robot(robot=robot, name="my_nav_service") - -# Set the service to operate in waypoint mode and begin navigation -await my_nav.set_mode(Mode.ValueType.MODE_WAYPOINT) -``` - -{{% /tab %}} -{{% tab name="Go" %}} - -```go -myNav, err := navigation.FromRobot(robot, "my_nav_service") - -// Create a new waypoint at the specified latitude and longitude -location = geo.NewPoint(40.76275, -73.96) - -// Add waypoint to the service's data storage -err := myNav.AddWaypoint(context.Background(), location, nil) - -myNav, err := navigation.FromRobot(robot, "my_nav_service") - -// Set the service to operate in waypoint mode and begin navigation -mode, err := myNav.SetMode(context.Background(), Mode.MODE_WAYPOINT, nil) -``` - -{{% /tab %}} -{{% tab name="Viam app" %}} - -{{< imgproc src="/services/navigation/navigation-control-card.png" alt="An example control interface for a navigation service in the Viam app Control Tab." resize="1200x" class="imgzoom aligncenter" >}} - -{{% /tab %}} -{{< /tabs >}} - -
-
- -Use the navigation service to autonomously navigate a machine to defined waypoints. - -[Try the navigation service →](/tutorials/services/navigate-with-rover-base/) - -
-
-
-{{% /tab %}} -{{% tab name="Custom Logic" %}} -
- -{{< tabs >}} -{{% tab name="Python" %}} - -```python -my_twilio_svc = Generic.from_robot(robot=machine, name="my_twilio_svc") - -# Use a custom command to send a text message with Twilio -command = {"to": "+1 234 567 8901", "body": "Hello world!"} -result = await my_twilio_svc.do_command(command) -``` - -{{% /tab %}} -{{% tab name="Go" %}} - -```go -myTwilioSvc, err := generic.FromRobot(machine, "my_twilio_svc") - -// Use a custom command to send a text message with Twilio -command := map[string]interface{}{"to": "+1 234 567 8901", "body": "Hello world!"} -result, err := myTwilioSvc.DoCommand(context.Background(), command) -``` - -{{% /tab %}} -{{< /tabs >}} - -
-
- -Using the Viam Registry you can turn services and your own custom business logic into _{{< glossary_tooltip term_id="module" text="modules" >}}_. You can then deploy your modules to your machines. - -[Create a module →](/how-tos/create-module/) - -
-
-
-{{% /tab %}} -{{< /tabs >}} - -
-
-
- -## Go from one machine to thousands - -

- When you connect machines to the cloud you get fleet management tools that let you scale. Go from one prototype to thousands of machines you can manage and operate from one place using the Viam Cloud. -

-
- -{{< tabs class="horizontalheaders platform" navheader="Capabilities">}} -{{% tab name="Deployment" %}} - -
- -{{< tabs >}} -{{% tab name="Fragment" %}} - -```json -// Reusable configuration for using a software package -{ - "services": [ - { - "name": "speech-1", - "namespace": "viam-labs", - "type": "speech", - "model": "viam-labs:speech:speechio" - } - ], - "modules": [ - { - "type": "registry", - "name": "viam-labs_speech", - "module_id": "viam-labs:speech", - // Specific version to deploy - "version": "0.5.2" - } - ] -} -``` - -{{% /tab %}} -{{< /tabs >}} - -
-
- -Manage hardware and software for multiple machines using a built-in tool called _{{< glossary_tooltip term_id="fragment" text="fragments" >}}_. -You can make changes to some or all of your machines in one go. - -[Deploy packages across devices →](/how-tos/deploy-packages/) - -
-
-
- -{{% /tab %}} -{{% tab name="Provisioning" %}} - -
- -{{< tabs >}} -{{% tab name="Shell" %}} - -```sh {class="command-line" data-prompt="$" data-output="3-5,6,7"} -# Create configuration for provisioning machines with a fragment -echo "{ - "manufacturer": "Company", - "model": "SmartRover", - "fragment_id": "11d1059b-eaed-4ad8-9fd8-d60ad7386aa2" -}" >> viam-provisioning.json - -# Get and run the script to install viam on a board. -wget https://storage.googleapis.com/packages.viam.com/apps/viam-agent/preinstall.sh -chmod 755 preinstall.sh -sudo ./preinstall.sh -``` - -{{% /tab %}} -{{< /tabs >}} - -
-
- -Provisioning allows you to complete part of the machine setup during the manufacturing process. The rest of the first-time setup happens once the machine is taken into operation. -This way, machines automatically get the latest updates. - -[Learn about provisioning →](/fleet/provision/) - -
-
-
- -{{% /tab %}} -{{% tab name="Observability" %}} - -
- -{{< tabs >}} -{{% tab name="Viam app" %}} - -{{< imgproc src="/fleet/dashboard.png" alt="Dashboard view of machine status information" resize="1200x" class="imgzoom aligncenter" >}} - -{{% /tab %}} -{{% tab name="Python" %}} - -```python -# Get all machines in a location -machines = await cloud.list_robots(location_id="abcde1fghi") - -for m in machines: - # Connect and get status information or latest logs - machine_parts = await cloud.get_robot_parts(m.id) - main_part = next(filter(lambda part: part.main_part, machine_parts), None) - - try: - # Get status for machine - machine = await connect(main_part.fqdn) - status = await machine.get_machine_status() - except ConnectionError: - # If no connection can be made, get last logs - logs = await cloud.get_robot_part_logs( - robot_part_id=main_part.id, num_log_entries=5) -``` - -{{% /tab %}} -{{< /tabs >}} - -
-
- -Get status information and logs from all your deployed machines. - -[Learn about Platform APIs →](/appendix/apis/#platform-apis) - -
-
-
- -{{% /tab %}} -{{% tab name="ML Training" %}} - -
- -{{< tabs >}} -{{% tab name="Viam app" %}} - -{{< imgproc src="/tutorials/data-management/train-model.png" alt="The data tab showing the train a model pane" resize="1200x" class="imgzoom" >}} - -{{% /tab %}} -{{% tab name="Python" %}} - -```python -# Start a training job to create a classification model based on the dataset -job_id = await ml_training_client.submit_training_job( - org_id="abbc1c1c-d2e3-5f67-ab8c-de912345f678", - dataset_id="12ab3cd4e56f7abc89de1fa2", - model_name="recognize_gestures", - model_version="1", - model_type=ModelType.MODEL_TYPE_MULTI_LABEL_CLASSIFICATION, - tags=["follow", "stop"] -) - -# Get status information for training job -job_metadata = await ml_training_client.get_training_job( - id=job_id) -``` - -{{% /tab %}} -{{< /tabs >}} - -
-
- -Build machine learning models based on your machines' data. You can pick from different training algorithms or create your own. - -[Train and deploy ML models →](/how-tos/train-deploy-ml/) - -
-
-
- -{{% /tab %}} -{{% tab name="Collaboration" %}} - -
- -{{< tabs >}} -{{% tab name="Viam app" %}} - -{{}} - -{{% /tab %}} -{{% tab name="Python" %}} - -```python -# Create a new machine -new_machine_id = await cloud.new_robot( - name="new-machine", location_id="abcde1fghi") - -# Get organization associated with authenticated user / API key -org_list = await cloud.list_organizations() - -# Create a new API key with owner access for the new machine -auth = APIKeyAuthorization( - role="owner", - resource_type="robot", - resource_id=new_machine_id -) -api_key, api_key_id = await cloud.create_key( - org_list[0].id, [auth], "key_for_new_machine") -``` - -{{% /tab %}} -{{< /tabs >}} - -
-
- -Viam allows you to organize and manage any number of machines. When collaborating with others, you can assign permissions using Role-Based Access Control (RBAC). - -[Learn about access control →](/cloud/rbac/) - -
-
-
- -{{% /tab %}} -{{< /tabs >}} diff --git a/docs/ai/_index.md b/docs/ai/_index.md new file mode 100644 index 00000000000..4c6ebf513dd --- /dev/null +++ b/docs/ai/_index.md @@ -0,0 +1,10 @@ +--- +linkTitle: "Leverage AI" +title: "Leverage AI" +weight: 500 +layout: "docs" +type: "docs" +no_list: true +open_on_desktop: true +overview: true +--- diff --git a/docs/ai/act.md b/docs/ai/act.md new file mode 100644 index 00000000000..4adb7aea523 --- /dev/null +++ b/docs/ai/act.md @@ -0,0 +1,9 @@ +--- +linkTitle: "Act based on inferences" +title: "Act based on inferences" +weight: 70 +layout: "docs" +type: "docs" +no_list: true +description: "TODO" +--- diff --git a/docs/ai/advanced/_index.md b/docs/ai/advanced/_index.md new file mode 100644 index 00000000000..233056f4cda --- /dev/null +++ b/docs/ai/advanced/_index.md @@ -0,0 +1,8 @@ +--- +linkTitle: "Advanced" +title: "Advanced" +weight: 200 +layout: "empty" +type: "docs" +empty_page: true +--- diff --git a/docs/ai/advanced/conditional-sync.md b/docs/ai/advanced/conditional-sync.md new file mode 100644 index 00000000000..9d8fae77468 --- /dev/null +++ b/docs/ai/advanced/conditional-sync.md @@ -0,0 +1,9 @@ +--- +linkTitle: "Upload external data" +title: "Upload external data for training" +weight: 20 +layout: "docs" +type: "docs" +no_list: true +description: "TODO" +--- diff --git a/docs/ai/alert.md b/docs/ai/alert.md new file mode 100644 index 00000000000..8f26dda2ebc --- /dev/null +++ b/docs/ai/alert.md @@ -0,0 +1,9 @@ +--- +linkTitle: "Alert on inferences" +title: "Alert on inferences" +weight: 60 +layout: "docs" +type: "docs" +no_list: true +description: "TODO" +--- diff --git a/docs/ai/create-dataset.md b/docs/ai/create-dataset.md new file mode 100644 index 00000000000..060ff51f244 --- /dev/null +++ b/docs/ai/create-dataset.md @@ -0,0 +1,9 @@ +--- +linkTitle: "Create a dataset" +title: "Create a dataset" +weight: 10 +layout: "docs" +type: "docs" +no_list: true +description: "TODO" +--- diff --git a/docs/ai/deploy.md b/docs/ai/deploy.md new file mode 100644 index 00000000000..d8cc3a5953a --- /dev/null +++ b/docs/ai/deploy.md @@ -0,0 +1,9 @@ +--- +linkTitle: "Deploy model" +title: "Deploy a model" +weight: 40 +layout: "docs" +type: "docs" +no_list: true +description: "TODO" +--- diff --git a/docs/ai/reference/_index.md b/docs/ai/reference/_index.md new file mode 100644 index 00000000000..a11cc4cbac0 --- /dev/null +++ b/docs/ai/reference/_index.md @@ -0,0 +1,10 @@ +--- +linkTitle: "Reference" +title: "Reference" +weight: 300 +layout: "empty" +type: "docs" +empty_page: true +open_on_desktop: true +header_only: true +--- diff --git a/docs/appendix/apis/ml-training-client.md b/docs/ai/reference/ml-training-client.md similarity index 99% rename from docs/appendix/apis/ml-training-client.md rename to docs/ai/reference/ml-training-client.md index 1401bd2168e..9adb316b30e 100644 --- a/docs/appendix/apis/ml-training-client.md +++ b/docs/ai/reference/ml-training-client.md @@ -1,7 +1,7 @@ --- title: "Work with ML Training Jobs with Viam's ML Training API" linkTitle: "ML Training Client" -weight: 10 +weight: 30 type: "docs" description: "Use the ML training client API to manage ML training jobs taking place in Viam's cloud app." tags: ["cloud", "sdk", "viam-server", "networking", "apis", "ml model", "ml"] diff --git a/docs/services/ml/_index.md b/docs/ai/reference/ml.md similarity index 99% rename from docs/services/ml/_index.md rename to docs/ai/reference/ml.md index 60ed3d08fcd..af14cdaa7c5 100644 --- a/docs/services/ml/_index.md +++ b/docs/ai/reference/ml.md @@ -1,7 +1,7 @@ --- title: "ML Model Service" -linkTitle: "ML Model" -weight: 30 +linkTitle: "ML Model Service" +weight: 10 type: "docs" tags: ["data management", "ml", "model training"] aliases: diff --git a/docs/services/vision/_index.md b/docs/ai/reference/vision/_index.md similarity index 99% rename from docs/services/vision/_index.md rename to docs/ai/reference/vision/_index.md index 4599b314dfc..93b39080c02 100644 --- a/docs/services/vision/_index.md +++ b/docs/ai/reference/vision/_index.md @@ -1,6 +1,6 @@ --- title: "Vision Service" -linkTitle: "Computer Vision" +linkTitle: "Vision Service" weight: 20 type: "docs" description: "The vision service enables your machine to use its on-board cameras to intelligently see and interpret the world around it." diff --git a/docs/services/vision/color_detector.md b/docs/ai/reference/vision/color_detector.md similarity index 100% rename from docs/services/vision/color_detector.md rename to docs/ai/reference/vision/color_detector.md diff --git a/docs/services/vision/detector_3d_segmenter.md b/docs/ai/reference/vision/detector_3d_segmenter.md similarity index 100% rename from docs/services/vision/detector_3d_segmenter.md rename to docs/ai/reference/vision/detector_3d_segmenter.md diff --git a/docs/services/vision/mlmodel.md b/docs/ai/reference/vision/mlmodel.md similarity index 100% rename from docs/services/vision/mlmodel.md rename to docs/ai/reference/vision/mlmodel.md diff --git a/docs/services/vision/obstacles_depth.md b/docs/ai/reference/vision/obstacles_depth.md similarity index 100% rename from docs/services/vision/obstacles_depth.md rename to docs/ai/reference/vision/obstacles_depth.md diff --git a/docs/services/vision/obstacles_distance.md b/docs/ai/reference/vision/obstacles_distance.md similarity index 100% rename from docs/services/vision/obstacles_distance.md rename to docs/ai/reference/vision/obstacles_distance.md diff --git a/docs/services/vision/obstacles_pointcloud.md b/docs/ai/reference/vision/obstacles_pointcloud.md similarity index 100% rename from docs/services/vision/obstacles_pointcloud.md rename to docs/ai/reference/vision/obstacles_pointcloud.md diff --git a/docs/ai/run-inference.md b/docs/ai/run-inference.md new file mode 100644 index 00000000000..9587691af18 --- /dev/null +++ b/docs/ai/run-inference.md @@ -0,0 +1,9 @@ +--- +linkTitle: "Run inference" +title: "Run inference on a model" +weight: 50 +layout: "docs" +type: "docs" +no_list: true +description: "TODO" +--- diff --git a/docs/ai/train-tflite.md b/docs/ai/train-tflite.md new file mode 100644 index 00000000000..0149e8e9041 --- /dev/null +++ b/docs/ai/train-tflite.md @@ -0,0 +1,9 @@ +--- +linkTitle: "Train TFlite model" +title: "Train a TFlite model" +weight: 20 +layout: "docs" +type: "docs" +no_list: true +description: "TODO" +--- diff --git a/docs/ai/train.md b/docs/ai/train.md new file mode 100644 index 00000000000..4d8c06f95b9 --- /dev/null +++ b/docs/ai/train.md @@ -0,0 +1,9 @@ +--- +linkTitle: "Train other models" +title: "Train other models" +weight: 30 +layout: "docs" +type: "docs" +no_list: true +description: "TODO" +--- diff --git a/docs/appendix/_index.md b/docs/appendix/_index.md deleted file mode 100644 index 37f744a50b1..00000000000 --- a/docs/appendix/_index.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: "Appendix" -linkTitle: "Appendix" -weight: 900 -empty_node: true -layout: "empty" -notoc: true -type: "docs" -description: "Reference and Background Material" -canonical: "/appendix/changelog/" ---- diff --git a/docs/appendix/apis/_index.md b/docs/appendix/apis/_index.md deleted file mode 100644 index b02f0167d56..00000000000 --- a/docs/appendix/apis/_index.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -title: "Viam's Client APIs" -linkTitle: "APIs" -weight: 20 -type: "docs" -description: "Access and control your machine or fleet with the SDKs' client libraries for the resource and robot APIs." -icon: true -images: ["/services/icons/sdk.svg"] -tags: ["client", "sdk", "viam-server", "networking", "apis", "robot api"] -aliases: - - /program/sdks/ - - /program/apis/ - - /build/program/apis/ -no_list: true -date: "2024-10-01" -# updated: "" # When the content was last entirely checked ---- - -Every Viam {{< glossary_tooltip term_id="resource" text="resource" >}} exposes an [application programming interface (API)](https://en.wikipedia.org/wiki/API) described through [protocol buffers](https://developers.google.com/protocol-buffers). - -The API methods provided by the SDKs for each of these resource APIs wrap gRPC client requests to the machine when you execute your program, providing you a convenient interface for accessing information about and controlling the {{< glossary_tooltip term_id="resource" text="resources" >}} you have [configured](/configure/) on your machine. - -## Platform APIs - -{{< cards >}} -{{% manualcard link="/appendix/apis/fleet/" title="Fleet Management API" %}} - -Create and manage organizations, locations, and machines, get logs from individual machines, and manage fragments and permissions. - -{{% /manualcard %}} -{{% manualcard link="/appendix/apis/data-client/" title="Data Client API" %}} - -Upload, download, filter, tag or perform other tasks on data like images or sensor readings. - -{{% /manualcard %}} -{{% manualcard link="/appendix/apis/robot/" title="Machine Management API" %}} - -Manage your machines: connect to your machine, retrieve status information, and send commands remotely. - -{{% /manualcard %}} -{{% manualcard link="/appendix/apis/ml-training-client/" title="ML Training Client API" %}} - -Submit and manage ML training jobs running on the Viam app. - -{{% /manualcard %}} -{{% manualcard link="/appendix/apis/billing-client/" title="Billing Client API" %}} - -Retrieve billing information from the Viam app. - -{{% /manualcard %}} - -{{< /cards >}} - -## Component APIs - -These APIs provide interfaces for controlling and getting information from the {{< glossary_tooltip term_id="component" text="components" >}} of a machine: - -{{< cards >}} -{{< card link="/appendix/apis/components/arm/" customTitle="Arm API" noimage="True" >}} -{{< card link="/appendix/apis/components/base/" customTitle="Base API" noimage="True" >}} -{{< card link="/appendix/apis/components/board/" customTitle="Board API" noimage="True" >}} -{{< card link="/appendix/apis/components/camera/" customTitle="Camera API" noimage="True" >}} -{{< card link="/appendix/apis/components/encoder/" customTitle="Encoder API" noimage="True" >}} -{{< card link="/appendix/apis/components/gantry/" customTitle="Gantry API" noimage="True" >}} -{{< card link="/appendix/apis/components/generic/" customTitle="Generic API" noimage="True" >}} -{{< card link="/appendix/apis/components/gripper/" customTitle="Gripper API" noimage="True" >}} -{{< card link="/appendix/apis/components/input-controller/" customTitle="Input controller API" noimage="True" >}} -{{< card link="/appendix/apis/components/motor/" customTitle="Motor API" noimage="True" >}} -{{< card link="/appendix/apis/components/movement-sensor/" customTitle="Movement sensor API" noimage="True" >}} -{{< card link="/appendix/apis/components/power-sensor/" customTitle="Power sensor API" noimage="True" >}} -{{< card link="/appendix/apis/components/sensor/" customTitle="Sensor API" noimage="True" >}} -{{< card link="/appendix/apis/components/servo/" customTitle="Servo API" noimage="True" >}} -{{< /cards >}} - -## Service APIs - -These APIs provide interfaces for controlling and getting information from the services you configured on a machine. - -{{< cards >}} -{{% card link="/appendix/apis/services/data/" customTitle="Data management service API" noimage="True" %}} -{{% card link="/appendix/apis/services/vision/" customTitle="Vision service API" noimage="True" %}} -{{% card link="/appendix/apis/services/ml/" customTitle="ML model service API" noimage="True" %}} -{{% card link="/appendix/apis/services/motion/" customTitle="Motion service API" noimage="True" %}} -{{% card link="/appendix/apis/services/navigation/" customTitle="Navigation service API" noimage="True" %}} -{{% card link="/appendix/apis/services/generic/" customTitle="Generic service API" noimage="True" %}} -{{% card link="/appendix/apis/services/slam/" customTitle="SLAM service API" noimage="True" %}} -{{% card link="/appendix/apis/services/base-rc/" customTitle="Base Remote Control service API" noimage="True" %}} -{{< /cards >}} diff --git a/docs/appendix/apis/components/_index.md b/docs/appendix/apis/components/_index.md deleted file mode 100644 index 9c8eba83262..00000000000 --- a/docs/appendix/apis/components/_index.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -linkTitle: "Component APIs" -title: "Component APIs" -weight: 5 -empty_node: true -layout: "empty" -canonical: "/appendix/apis/" -type: "docs" ---- diff --git a/docs/appendix/apis/components/arm.md b/docs/appendix/apis/components/arm.md deleted file mode 100644 index 8448d550ef1..00000000000 --- a/docs/appendix/apis/components/arm.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -title: "Arm API" -linkTitle: "Arm" -weight: 10 -type: "docs" -description: "Give commands to your arm components for linear motion planning, including self-collision prevention and obstacle avoidance." -icon: true -images: ["/icons/components/arm.svg"] -date: "2022-01-01" -# updated: "" # When the content was last entirely checked ---- - -The arm API allows you to give commands to your [arm components](/components/arm/) for linear motion planning, including self-collision prevention and obstacle avoidance. - -The arm component supports the following methods: - -{{< readfile "/static/include/components/apis/generated/arm-table.md" >}} - -## Establish a connection - -To get started using Viam's SDKs to connect to and control your arm and the rest of your machine, go to your machine's page on the [Viam app](https://app.viam.com), -Navigate to the **CONNECT** tab's **Code sample** page, select your preferred programming language, and copy the sample code. - -{{% snippet "show-secret.md" %}} - -When executed, this sample code creates a connection to your machine as a client. - -The following examples assume you have an arm called `"my_arm"` configured as a component of your machine. -If your arm has a different name, change the `name` in the code. - -Import the arm package for the SDK you are using: - -{{< tabs >}} -{{% tab name="Python" %}} - -```python -from viam.components.arm import Arm -# To use move_to_position: -from viam.proto.common import Pose -# To use move_to_joint_positions: -from viam.proto.component.arm import JointPositions -``` - -{{% /tab %}} -{{% tab name="Go" %}} - -```go -import ( - "go.viam.com/rdk/components/arm" - // To use MoveToPosition: - "go.viam.com/rdk/referenceframe" - "go.viam.com/rdk/spatialmath" - // To use MoveToJointPositions ("armapi" name optional, but necessary if importing other packages called "v1"): - armapi "go.viam.com/api/component/arm/v1" -) -``` - -{{% /tab %}} -{{< /tabs >}} - -## API - -{{< readfile "/static/include/components/apis/generated/arm.md" >}} diff --git a/docs/appendix/apis/components/base.md b/docs/appendix/apis/components/base.md deleted file mode 100644 index 31203c21f88..00000000000 --- a/docs/appendix/apis/components/base.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: "Base API" -linkTitle: "Base" -weight: 20 -type: "docs" -description: "Give commands for moving all configured components attached to a mobile platform as a whole without needing to send commands to individual components." -icon: true -images: ["/icons/components/base.svg"] -date: "2022-01-01" -# updated: "" # When the content was last entirely checked ---- - -The base API allows you to give commands to your [base components](/components/base/) for moving all configured components attached to a platform as a whole without needing to send commands to individual components. - -The base component supports the following methods: - -{{< readfile "/static/include/components/apis/generated/base-table.md" >}} - -## Establish a connection - -To get started using Viam's SDKs to connect to and control your base and the rest of your machine, go to your machine's page on the [Viam app](https://app.viam.com), -Navigate to the **CONNECT** tab's **Code sample** page, select your preferred programming language, and copy the sample code. - -{{% snippet "show-secret.md" %}} - -When executed, this sample code creates a connection to your machine as a client. - -The following examples assume you have a wheeled base called `"my_base"` configured as a component of your machine. -If your base has a different name, change the `name` in the code. - -Import the base package for the SDK you are using: - -{{< tabs >}} -{{% tab name="Python" %}} - -```python -from viam.components.base import Base -``` - -{{% /tab %}} -{{% tab name="Go" %}} - -```go -import ( - "go.viam.com/rdk/components/base" -) -``` - -{{% /tab %}} -{{< /tabs >}} - -## API - -{{< readfile "/static/include/components/apis/generated/base.md" >}} diff --git a/docs/appendix/apis/components/board.md b/docs/appendix/apis/components/board.md deleted file mode 100644 index 20321ad6018..00000000000 --- a/docs/appendix/apis/components/board.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -title: "Board API" -linkTitle: "Board" -weight: 30 -type: "docs" -description: "Give commands for setting GPIO pins to high or low, setting PWM, and working with analog and digital interrupts." -icon: true -images: ["/icons/components/board.svg"] -date: "2022-01-01" -# updated: "" # When the content was last entirely checked ---- - -The board API allows you to give commands to your [board components](/components/board/) for setting GPIO pins to high or low, setting PWM, and working with analog and digital interrupts. - -The board component supports the following methods: - -{{< readfile "/static/include/components/apis/generated/board-table.md" >}} - -## Establish a connection - -To get started using Viam's SDKs to connect to and control your board and the rest of your machine, go to your machine's page on the [Viam app](https://app.viam.com), -Navigate to the **CONNECT** tab's **Code sample** page, select your preferred programming language, and copy the sample code. - -{{% snippet "show-secret.md" %}} - -When executed, this sample code will create a connection to your machine as a client. -Then control your machine programmatically by getting your `board` component from the machine with `FromRobot` and adding API method calls, as shown in the following examples. - -The following examples assume you have a board called `"my_board"` configured as a component of your machine. -If your board has a different name, change the `name` in the code. - -Import the board package for the SDK you are using: - -{{< tabs >}} -{{% tab name="Python" %}} - -```python -from viam.components.board import Board -``` - -{{% /tab %}} -{{% tab name="Go" %}} - -```go -import ( - "go.viam.com/rdk/components/board" -) -``` - -{{% /tab %}} -{{< /tabs >}} - -## API - -{{< readfile "/static/include/components/apis/generated/board.md" >}} diff --git a/docs/appendix/apis/components/camera.md b/docs/appendix/apis/components/camera.md deleted file mode 100644 index 389a0f6ae80..00000000000 --- a/docs/appendix/apis/components/camera.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: "Camera API" -linkTitle: "Camera" -weight: 40 -type: "docs" -description: "Give commands for getting images or point clouds." -icon: true -images: ["/icons/components/camera.svg"] -date: "2022-01-01" -# updated: "" # When the content was last entirely checked ---- - -The camera API allows you to give commands to your [camera components](/components/camera/) for getting images or point clouds. - -The API for camera components allows you to: - -- Request single images or a stream in 2D color, or display z-depth. -- Request a point cloud. - Each 3D point cloud image consists of a set of coordinates (x,y,z) representing depth in mm. - -The camera component supports the following methods: - -{{< readfile "/static/include/components/apis/generated/camera-table.md" >}} - -## Establish a connection - -To get started using Viam's SDKs to connect to and control your camera and the rest of your machine, go to your machine's page on the [Viam app](https://app.viam.com), -Navigate to the **CONNECT** tab's **Code sample** page, select your preferred programming language, and copy the sample code. - -{{% snippet "show-secret.md" %}} - -When executed, this sample code creates a connection to your machine as a client. - -The following examples assume you have a camera called `"my_camera"` configured as a component of your machine. -If your camera has a different name, change the `name` in the code. - -Import the camera package for the SDK you are using: - -{{< tabs >}} -{{% tab name="Python" %}} - -```python -from viam.components.camera import Camera -``` - -{{% /tab %}} -{{% tab name="Go" %}} - -```go -import ( - "go.viam.com/rdk/components/camera" -) -``` - -{{% /tab %}} -{{< /tabs >}} - -## API - -{{< readfile "/static/include/components/apis/generated/camera.md" >}} diff --git a/docs/appendix/apis/components/encoder.md b/docs/appendix/apis/components/encoder.md deleted file mode 100644 index f360c18b954..00000000000 --- a/docs/appendix/apis/components/encoder.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: "Encoder API" -linkTitle: "Encoder" -weight: 50 -type: "docs" -description: "Give commands for getting the position of a motor or a joint in ticks or degrees." -icon: true -images: ["/icons/components/encoder.svg"] -date: "2022-01-01" -# updated: "" # When the content was last entirely checked ---- - -The encoder API allows you to give commands to your [encoder components](/components/encoder/) for getting the position of a motor or a joint in ticks or degrees. - -The encoder component supports the following methods: - -{{< readfile "/static/include/components/apis/generated/encoder-table.md" >}} - -## Establish a connection - -To get started using Viam's SDKs to connect to and control your encoder and the rest of your machine, go to your machine's page on the [Viam app](https://app.viam.com), -Navigate to the **CONNECT** tab's **Code sample** page, select your preferred programming language, and copy the sample code. - -{{% snippet "show-secret.md" %}} - -When executed, this sample code creates a connection to your machine as a client. - -The following examples assume you have an encoder called `"my_encoder"` configured as a component of your machine. -If your encoder has a different name, change the `name` in the code. - -Import the encoder package for the SDK you are using: - -{{< tabs >}} -{{% tab name="Python" %}} - -```python -from viam.components.encoder import Encoder -``` - -{{% /tab %}} -{{% tab name="Go" %}} - -```go -import ( - "go.viam.com/rdk/components/encoder" -) -``` - -{{% /tab %}} -{{< /tabs >}} - -## API - -{{< readfile "/static/include/components/apis/generated/encoder.md" >}} diff --git a/docs/appendix/apis/components/gantry.md b/docs/appendix/apis/components/gantry.md deleted file mode 100644 index 5d474ee2bcf..00000000000 --- a/docs/appendix/apis/components/gantry.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: "Gantry API" -linkTitle: "Gantry" -weight: 60 -type: "docs" -description: "Give commands for coordinated control of one or more linear actuators." -icon: true -images: ["/icons/components/gantry.svg"] -date: "2022-01-01" -# updated: "" # When the content was last entirely checked ---- - -The gantry API allows you to give commands to your [gantry components](/components/gantry/) for coordinated control of one or more linear actuators. - -The gantry component supports the following methods: - -{{< readfile "/static/include/components/apis/generated/gantry-table.md" >}} - -## Establish a connection - -To get started using Viam's SDKs to connect to and control your gantry and the rest of your machine, go to your machine's page on the [Viam app](https://app.viam.com), -Navigate to the **CONNECT** tab's **Code sample** page, select your preferred programming language, and copy the sample code. - -{{% snippet "show-secret.md" %}} - -When executed, this sample code creates a connection to your machine as a client. - -The following examples assume you have a gantry called `"my_gantry"` configured as a component of your machine. -If your gantry has a different name, change the `name` in the code. - -Import the gantry package for the SDK you are using: - -{{< tabs >}} -{{% tab name="Python" %}} - -```python -from viam.components.gantry import Gantry -``` - -{{% /tab %}} -{{% tab name="Go" %}} - -```go -import ( - "go.viam.com/rdk/components/gantry" -) -``` - -{{% /tab %}} -{{< /tabs >}} - -## API - -{{< readfile "/static/include/components/apis/generated/gantry.md" >}} diff --git a/docs/appendix/apis/components/generic.md b/docs/appendix/apis/components/generic.md deleted file mode 100644 index 1503914b0f0..00000000000 --- a/docs/appendix/apis/components/generic.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -title: "Control your generic component with the generic API" -linkTitle: "Generic" -weight: 70 -type: "docs" -description: "Give commands for running custom model-specific commands using DoCommand on your generic components." -icon: true -images: ["/icons/components/generic.svg"] -date: "2022-01-01" -# updated: "" # When the content was last entirely checked ---- - -The generic API allows you to give commands to your [generic components](/components/generic/) for running model-specific commands using [`DoCommand`](/appendix/apis/components/generic/#docommand). - -The generic component supports the following method: - -{{< readfile "/static/include/components/apis/generated/generic_component-table.md" >}} - -## Establish a connection - -To get started using Viam's SDKs to connect to and control your generic component and the rest of your machine, go to your machine's page on the [Viam app](https://app.viam.com), -Navigate to the **CONNECT** tab's **Code sample** page, select your preferred programming language, and copy the sample code. - -{{% snippet "show-secret.md" %}} - -When executed, this sample code will create a connection to your machine as a client. -Then control your machine programmatically by getting your `generic` component from the machine with `FromRobot` and adding API method calls, as shown in the following examples. - -The following examples assume you have a board called "my_board" configured as a component of your machine. -If your board has a different name, change the `name` in the code. - -Import the generic component package for the SDK you are using: - -{{< tabs >}} -{{% tab name="Python" %}} - -```python -from viam.components.generic import Generic -``` - -{{% /tab %}} -{{% tab name="Go" %}} - -```go -import ( - "go.viam.com/rdk/components/generic" -) -``` - -{{% /tab %}} -{{% tab name="C++" %}} - -```cpp -#include -``` - -{{% /tab %}} -{{< /tabs >}} - -## API - -{{< readfile "/static/include/components/apis/generated/generic_component.md" >}} diff --git a/docs/appendix/apis/components/gripper.md b/docs/appendix/apis/components/gripper.md deleted file mode 100644 index 35000b696a3..00000000000 --- a/docs/appendix/apis/components/gripper.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: "Control your gripper with the gripper API" -linkTitle: "Gripper" -weight: 80 -type: "docs" -description: "Give commands for opening and closing a gripper device." -icon: true -images: ["/icons/components/gripper.svg"] -date: "2022-01-01" -# updated: "" # When the content was last entirely checked ---- - -The gripper API allows you to give commands to your [gripper components](/components/gripper/) for opening and closing a device. - -The gripper component supports the following methods: - -{{< readfile "/static/include/components/apis/generated/gripper-table.md" >}} - -## Establish a connection - -To get started using Viam's SDKs to connect to and control your gripper and the rest of your machine, go to your machine's page on the [Viam app](https://app.viam.com), -Navigate to the **CONNECT** tab's **Code sample** page, select your preferred programming language, and copy the sample code. - -{{% snippet "show-secret.md" %}} - -When executed, this sample code creates a connection to your machine as a client. - -The following examples assume you have a gripper called `"my_gripper"` configured as a component of your machine. -If your gripper has a different name, change the `name` in the code. - -Import the gripper package for the SDK you are using: - -{{< tabs >}} -{{% tab name="Python" %}} - -```python -from viam.components.gripper import Gripper -``` - -{{% /tab %}} -{{% tab name="Go" %}} - -```go -import ( - "go.viam.com/rdk/components/gripper" -) -``` - -{{% /tab %}} -{{< /tabs >}} - -## API - -{{< readfile "/static/include/components/apis/generated/gripper.md" >}} diff --git a/docs/appendix/apis/components/input-controller.md b/docs/appendix/apis/components/input-controller.md deleted file mode 100644 index 3bd12e87292..00000000000 --- a/docs/appendix/apis/components/input-controller.md +++ /dev/null @@ -1,574 +0,0 @@ ---- -title: "Input controller API" -linkTitle: "Input Controller" -titleMustBeLong: true -weight: 90 -type: "docs" -description: "Give commands to register callbacks for events, allowing you to use input devices to control your machines." -icon: true -images: ["/icons/components/controller.svg"] -date: "2022-01-01" -# updated: "" # When the content was last entirely checked ---- - -The input controller API allows you to give commands to your [input controller components](/components/input-controller/) for configuring callbacks for events, allowing you to configure input devices to control your machines. - -The input controller component supports the following methods: - -{{< readfile "/static/include/components/apis/generated/input_controller-table.md" >}} - -## Establish a connection - -To get started using Viam's SDKs to connect to and control your controller and the rest of your machine, go to your machine's page on the [Viam app](https://app.viam.com), -Navigate to the **CONNECT** tab's **Code sample** page, select your preferred programming language, and copy the sample code. - -{{% snippet "show-secret.md" %}} - -When executed, this sample code creates a connection to your machine as a client. - -The following examples assume you have an input controller called `"my_controller"` configured as a component of your machine. -If your input controller has a different name, change the `name` in the code. - -Import the input controller package for the SDK you are using: - -{{< tabs >}} -{{% tab name="Python" %}} - -```python -from viam.components.input import Control, Controller, EventType -``` - -{{% /tab %}} -{{% tab name="Go" %}} - -```go -import ( - "go.viam.com/rdk/components/input" -) -``` - -{{% /tab %}} -{{< /tabs >}} - -## API - -{{< readfile "/static/include/components/apis/generated/input_controller.md" >}} - -## API types - -The `input` API defines the following types: - -### Event object - -Each `Event` object represents a singular event from the input device, and has four fields: - -1. `Time`: `time.Time` the event occurred. -2. `Event`: `EventType` indicating the type of event (for example, a specific button press or axis movement). -3. `Control`: `Control` indicating which [Axis](#axis-controls), [Button](/appendix/apis/components/input-controller/#button-controls), or Pedal on the controller has been changed. -4. `Value`: `float64` indicating the position of an [Axis](/appendix/apis/components/input-controller/#axis-controls) or the state of a [Button](/appendix/apis/components/input-controller/#button-controls) on the specified control. - -#### EventType field - -A string-like type indicating the specific type of input event, such as a button press or axis movement. - -- To select for events of all type when registering callback function with [RegisterControlCallback](/appendix/apis/components/input-controller/#registercontrolcallback), you can use `AllEvents` as your `EventType`. -- The registered function is then called in addition to any other callback functions you've registered, every time an `Event` happens on your controller. - This is useful for debugging without interrupting normal controls, or for capturing extra or unknown events. - -Registered `EventTypes` definitions: - -{{< tabs >}} -{{% tab name="Python" %}} - -```python {class="line-numbers linkable-line-numbers"} -ALL_EVENTS = "AllEvents" -""" -Callbacks registered for this event will be called in ADDITION to other -registered event callbacks. -""" - -CONNECT = "Connect" -""" -Sent at controller initialization, and on reconnects. -""" - -DISCONNECT = "Disconnect" -""" -If unplugged, or wireless/network times out. -""" - -BUTTON_PRESS = "ButtonPress" -""" -Typical key press. -""" - -BUTTON_RELEASE = "ButtonRelease" -""" -Key release. -""" - -BUTTON_HOLD = "ButtonHold" -""" -Key is held down. This will likely be a repeated event. -""" - -BUTTON_CHANGE = "ButtonChange" -""" -Both up and down for convenience during registration, not typically emitted. -""" - -POSITION_CHANGE_ABSOLUTE = "PositionChangeAbs" -""" -Absolute position is reported via Value, a la joysticks. -""" - -POSITION_CHANGE_RELATIVE = "PositionChangeRel" -""" -Relative position is reported via Value, a la mice, or simulating axes with -up/down buttons. -""" -``` - -See [the Python SDK Docs](https://python.viam.dev/autoapi/viam/components/input/input/index.html#viam.components.input.EventType) for the most current version of supported `EventTypes`. - -{{% /tab %}} -{{% tab name="Go" %}} - -```go {class="line-numbers linkable-line-numbers"} - // Callbacks registered for this event will be called in ADDITION to other registered event callbacks. -AllEvents EventType = "AllEvents" - -// Sent at controller initialization, and on reconnects. -Connect EventType = "Connect" - -// If unplugged, or wireless/network times out. -Disconnect EventType = "Disconnect" - -// Typical key press. -ButtonPress EventType = "ButtonPress" - -// Key release. -ButtonRelease EventType = "ButtonRelease" - -// Key is held down. This will likely be a repeated event. -ButtonHold EventType = "ButtonHold" - -// Both up and down for convenience during registration, not typically emitted. -ButtonChange EventType = "ButtonChange" - -// Absolute position is reported via Value, a la joysticks. -PositionChangeAbs EventType = "PositionChangeAbs" - -// Relative position is reported via Value, a la mice, or simulating axes with up/down buttons. -PositionChangeRel EventType = "PositionChangeRel" -``` - -See [the Viam RDK](https://github.com/viamrobotics/rdk/blob/main/components/input/input.go) for the most current version of supported `EventTypes`. - -{{% /tab %}} -{{< /tabs >}} - -#### Control field - -A string representing the physical input location, like a specific axis or button, of your `Controller` that the [Event Object](#event-object) is coming from. - -Registered `Control` types are defined as follows: - -{{< tabs >}} -{{% tab name="Python" %}} - -```python {class="line-numbers linkable-line-numbers"} -# Axes -ABSOLUTE_X = "AbsoluteX" -ABSOLUTE_Y = "AbsoluteY" -ABSOLUTE_Z = "AbsoluteZ" -ABSOLUTE_RX = "AbsoluteRX" -ABSOLUTE_RY = "AbsoluteRY" -ABSOLUTE_RZ = "AbsoluteRZ" -ABSOLUTE_HAT0_X = "AbsoluteHat0X" -ABSOLUTE_HAT0_Y = "AbsoluteHat0Y" - -# Buttons -BUTTON_SOUTH = "ButtonSouth" -BUTTON_EAST = "ButtonEast" -BUTTON_WEST = "ButtonWest" -BUTTON_NORTH = "ButtonNorth" -BUTTON_LT = "ButtonLT" -BUTTON_RT = "ButtonRT" -BUTTON_LT2 = "ButtonLT2" -BUTTON_RT2 = "ButtonRT2" -BUTTON_L_THUMB = "ButtonLThumb" -BUTTON_R_THUMB = "ButtonRThumb" -BUTTON_SELECT = "ButtonSelect" -BUTTON_START = "ButtonStart" -BUTTON_MENU = "ButtonMenu" -BUTTON_RECORD = "ButtonRecord" -BUTTON_E_STOP = "ButtonEStop" - -# Pedals -ABSOLUTE_PEDAL_ACCELERATOR = "AbsolutePedalAccelerator" -ABSOLUTE_PEDAL_BRAKE = "AbsolutePedalBrake" -ABSOLUTE_PEDAL_CLUTCH = "AbsolutePedalClutch" -``` - -See [the Python SDK Docs](https://python.viam.dev/autoapi/viam/components/input/input/index.html#viam.components.input.Control) for the most current version of supported `Control` types. - -{{% /tab %}} -{{% tab name="Go" %}} - -```go {class="line-numbers linkable-line-numbers"} -// Axes. -AbsoluteX Control = "AbsoluteX" -AbsoluteY Control = "AbsoluteY" -AbsoluteZ Control = "AbsoluteZ" -AbsoluteRX Control = "AbsoluteRX" -AbsoluteRY Control = "AbsoluteRY" -AbsoluteRZ Control = "AbsoluteRZ" -AbsoluteHat0X Control = "AbsoluteHat0X" -AbsoluteHat0Y Control = "AbsoluteHat0Y" - -// Buttons. -ButtonSouth Control = "ButtonSouth" -ButtonEast Control = "ButtonEast" -ButtonWest Control = "ButtonWest" -ButtonNorth Control = "ButtonNorth" -ButtonLT Control = "ButtonLT" -ButtonRT Control = "ButtonRT" -ButtonLT2 Control = "ButtonLT2" -ButtonRT2 Control = "ButtonRT2" -ButtonLThumb Control = "ButtonLThumb" -ButtonRThumb Control = "ButtonRThumb" -ButtonSelect Control = "ButtonSelect" -ButtonStart Control = "ButtonStart" -ButtonMenu Control = "ButtonMenu" -ButtonRecord Control = "ButtonRecord" -ButtonEStop Control = "ButtonEStop" - -// Pedals. -AbsolutePedalAccelerator Control = "AbsolutePedalAccelerator" -AbsolutePedalBrake Control = "AbsolutePedalBrake" -AbsolutePedalClutch Control = "AbsolutePedalClutch" -``` - -See [GitHub](https://github.com/viamrobotics/rdk/blob/main/components/input/input.go) for the most current version of supported `Control` types. - -{{% /tab %}} -{{< /tabs >}} - -### Axis controls - -{{% alert title="Support Notice" color="note" %}} -Currently, only `Absolute` axes are supported. - -`Relative` axes, reporting a relative change in distance, used by devices like mice and trackpads, will be supported in the future. -{{% /alert %}} - -Analog devices like joysticks and thumbsticks which return to center/neutral on their own use `Absolute` axis control types. - -These controls report a `PositionChangeAbs` [EventType](#eventtype-field). - -**Value:** A `float64` between `-1.0` and `+1.0`. - -- `1.0`: Maximum position in the positive direction. -- `0.0`: Center, neutral position. -- `-1.0`: Maximum position in the negative direction. - -#### AbsoluteXY axes - -If your input controller has an analog stick, this is what the stick's controls report as. - -Alternatively, if your input controller has _two_ analog sticks, this is what the left joystick's controls report as. - -| Name | `-1.0` | `0.0` | `1.0` | -| ----------- | ------------- | ------- | --------------- | -| `AbsoluteX` | Stick Left | Neutral | Stick Right | -| `AbsoluteY` | Stick Forward | Neutral | Stick Backwards | - -#### AbsoluteR-XY axes - -If your input controller has _two_ analog sticks, this is what the right joystick's controls report as. - -| Name | `-1.0` | `0.0` | `1.0` | -| ------------ | ------------- | ------- | --------------- | -| `AbsoluteRX` | Stick Left | Neutral | Stick Right | -| `AbsoluteRY` | Stick Forward | Neutral | Stick Backwards | - -- For `Y` axes, the positive direction is "nose up," and indicates _pulling_ back on the joystick. - -#### Hat/D-Pad axes - -If your input controller has a directional pad with analog buttons on the pad, this is what those controls report as. - - -| Name | `-1.0` | `0.0` | `1.0` | -| ---- | ------ | ----- | ----- | -| `AbsoluteHat0X` | Left DPAD Button Press | Neutral | Right DPAD Button Press | -| `AbsoluteHat0Y` | Up DPAD Button Press | Neutral | Down DPAD Button Press | - -#### Z axes (analog trigger sticks) - -{{% alert title="Info" color="info" %}} -Devices like analog triggers and gas or brake pedals use `Absolute` axes, but they only report position change in the positive direction. -The neutral point of the axes is still `0.0`. -{{% /alert %}} - -| Name | `-1.0` | `0.0` | `1.0` | -| ------------ | ------ | ------- | ------------ | -| `AbsoluteZ` | | Neutral | Stick Pulled | -| `AbsoluteRZ` | | Neutral | Stick Pulled | - -`Z` axes are usually not present on most controller joysticks. - -If present, they are typically analog trigger sticks, and unidirectional, scaling only from `0` to `1.0` as they are pulled, as shown above. - -`AbsoluteZ` is reported if there is one trigger stick, and `AbsoluteZ` (left) and `AbsoluteRZ` (right) is reported if there are two trigger sticks. - -Z axes can be present on flight-style joysticks, reporting _yaw_, or left/right rotation, as shown below. -This is not common. - -| Name | `-1.0` | `0.0` | `1.0` | -| ------------ | -------------- | ------- | --------------- | -| `AbsoluteZ` | Stick Left Yaw | Neutral | Stick Right Yaw | -| `AbsoluteRZ` | Stick Left Yaw | Neutral | Stick Right Yaw | - -### Button controls - -Button Controls report either `ButtonPress` or `ButtonRelease` as their [EventType](#eventtype-field). - -**Value:** - -- `0`: released -- `1`: pressed - -#### Action buttons (ABXY) - -If your input controller is a gamepad with digital action buttons, this is what the controls for these buttons report as. - -{{% alert title="Tip" color="tip" %}} -As different systems label the actual buttons differently, we use compass directions for consistency. - -- `ButtonSouth` corresponds to "B" on Nintendo, "A" on XBox, and "X" on Playstation. -- `ButtonNorth` corresponds to "X" on Nintendo, "Y" on XBox, and "Triangle" on Playstation. - {{% /alert %}} - - -| Diamond 4-Action Button Pad | Rectangle 4-Action Button Pad | -| - | - | -|
NameDescription
`ButtonNorth`Top
`ButtonSouth`Bottom
`ButtonEast`Right
`ButtonWest`Left
|
NameDescription
`ButtonNorth`Top-left
`ButtonSouth`Bottom-right
`ButtonEast`Top-right
`ButtonWest`Bottom-left
| - - -| Horizontal 3-Action Button Pad | Vertical 3-Action Button Pad | -| - | - | -|
NameDescription
`ButtonWest`Left
`ButtonSouth`Center
`ButtonEast`Right
|
NameDescription
`ButtonWest`Top
`ButtonSouth`Center
`ButtonEast`Bottom
| - - -| Horizontal 2-Action Button Pad | Vertical 2-Action Button Pad | -| - | - | -|
NameDescription
`ButtonEast`Right
`ButtonSouth`Left
|
NameDescription
`ButtonEast`Top
`ButtonSouth`Bottom
| - -#### Trigger buttons (bumpers) - -If your input controller is a gamepad with digital trigger buttons, this is what the controls for those buttons report as. - - -| 2-Trigger Button Pad | 4-Trigger Button Pad | -| - | - | -|
NameDescription
`ButtonLT`Left
`ButtonRT`Right
|
NameDescription
`ButtonLT`Top-left
`ButtonRT`Top-right
`ButtonLT2`Bottom-left
`ButtonRT2`Bottom-right
| - -#### Digital buttons for sticks - -If your input controller is a gamepad with "clickable" thumbsticks, this is what thumbstick presses report as. - -| Name | Description | -| -------------- | ------------------------------- | -| `ButtonLThumb` | Left or upper button for stick | -| `ButtonRThumb` | Right or lower button for stick | - -#### Miscellaneous buttons - -Many devices have additional buttons. -If your input controller is a gamepad with these common buttons, this is what the controls for those buttons report as. - -| Name | Description | -| -------------- | --------------------------------------------------- | -| `ButtonSelect` | Select or - | -| `ButtonStart` | Start or + | -| `ButtonMenu` | Usually the central "Home" or Xbox/PS "Logo" button | -| `ButtonRecord` | Recording | -| `ButtonEStop` | Emergency Stop (on some industrial controllers) | - -## Usage examples - -### Control a wheeled base with a Logitech G920 steering wheel controller - -The following Python code is an example of controlling a wheeled {{% glossary_tooltip term_id="base" text="base"%}} with a Logitech G920 steering wheel controller, configured as a `gamepad` input controller. - -```python {id="python-example" class="line-numbers linkable-line-numbers"} -import asyncio - -from viam.components.base import Base -from viam.components.input import Control, Controller, EventType -from viam.proto.common import Vector3 -from viam.robot.client import RobotClient -from viam.rpc.dial import Credentials, DialOptions - -turn_amt = 0 -modal = 0 -cmd = {} - - -async def connect_robot(host, api_key, api_key_id): - opts = RobotClient.Options.with_api_key( - api_key=api_key, - api_key_id=api_key_id - ) - return await RobotClient.at_address(host, opts) - - -def handle_turning(event): - global turn_amt - turn_amt = -event.value - print("turning:", turn_amt) - - -def handle_brake(event): - if event.value != 0: - print("braking!:", event.value) - global cmd - cmd = {"y": 0} - print("broke") - - -def handle_accelerator(event): - print("moving!:", event.value) - global cmd - accel = (event.value - 0.1) / 0.9 - if event.value < 0.1: - accel = 0 - - cmd = {"y": accel} - - -def handle_clutch(event): - print("moving!:", event.value) - global cmd - accel = (event.value - 0.1) / 0.9 - if event.value < 0.1: - accel = 0 - - cmd = {"y": -accel} - - -async def handleController(controller): - resp = await controller.get_events() - # Show the input controller's buttons/axes - print(f'Controls:\n{resp}') - - if Control.ABSOLUTE_PEDAL_ACCELERATOR in resp: - controller.register_control_callback( - Control.ABSOLUTE_PEDAL_ACCELERATOR, - [EventType.POSITION_CHANGE_ABSOLUTE], - handle_accelerator) - else: - print("Accelerator Pedal not found! Exiting! Are your steering wheel" + - " and pedals hooked up?") - exit() - - if Control.ABSOLUTE_PEDAL_BRAKE in resp: - controller.register_control_callback( - Control.ABSOLUTE_PEDAL_BRAKE, - [EventType.POSITION_CHANGE_ABSOLUTE], - handle_brake) - else: - print("Brake Pedal not found! Exiting!") - exit() - - if Control.ABSOLUTE_PEDAL_CLUTCH in resp: - controller.register_control_callback( - Control.ABSOLUTE_PEDAL_CLUTCH, - [EventType.POSITION_CHANGE_ABSOLUTE], - handle_clutch) - else: - print("Accelerator Pedal not found! Exiting! Are your steering wheel" + - " and pedals hooked up?") - exit() - - if Control.ABSOLUTE_X in resp: - controller.register_control_callback( - Control.ABSOLUTE_X, - [EventType.POSITION_CHANGE_ABSOLUTE], - handle_turning) - else: - print("Wheel not found! Exiting!") - exit() - - while True: - await asyncio.sleep(0.01) - global cmd - if "y" in cmd: - res = await modal.set_power( - linear=Vector3(x=0, y=cmd["y"], z=0), - angular=Vector3(x=0, y=0, z=turn_amt)) - cmd = {} - print(res) - - -async def main(): - # ADD YOUR MACHINE REMOTE ADDRESS and API KEY VALUES. - # These can be found in app.viam.com's CONNECT tab's Code sample page. - # Toggle 'Include API key' to show the API key values. - g920_robot = await connect_robot( - "robot123example.locationxyzexample.viam.com", "API_KEY", "API_KEY_ID") - modal_robot = await connect_robot( - "robot123example.locationxyzexample.viam.com", "API_KEY", "API_KEY_ID") - - g920 = Controller.from_robot(g920_robot, 'wheel') - global modal - modal = Base.from_robot(modal_robot, 'modal-base-server:base') - - await handleController(g920) - - await g920_robot.close() - await modal_robot.close() - -if __name__ == '__main__': - asyncio.run(main()) -``` - -### Drive a robot with four wheels and a skid steer platform - -The following Go code is part of an example of using an input controller to drive a robot with four wheels & a skid steer platform. - -The `motorCtl` callback function controls 5 motors: left front & back `FL` `BL`, right front & back `FL` `BL`, and a `winder` motor that raises and lowers a front-end like a bulldozer. - -The `event.Control` logic is registered as a callback function to determine the case for setting the power of each motor from which button is pressed on the input controller. - -```go {id="go-example" class="line-numbers linkable-line-numbers"} -// Define a single callback function -motorCtl := func(ctx context.Context, event input.Event) { - if event.Event != input.PositionChangeAbs { - return - } - - speed := float32(math.Abs(event.Value)) - - // Handle input events, commands to set the power of motor components (SetPower method) - switch event.Control { - case input.AbsoluteY: - motorFL.SetPower(ctx, speed, nil) - motorBL.SetPower(ctx, speed, nil) - case input.AbsoluteRY: - motorFR.SetPower(ctx, speed * -1, nil) - motorBR.SetPower(ctx, speed * -1, nil) - case input.AbsoluteZ: - motorWinder.SetPower(ctx, speed, nil) - case input.AbsoluteRZ: - motorWinder.SetPower(ctx, speed * -1, nil) - } -} - -// Registers callback from motorCtl for a selected set of axes -for _, control := range []input.Control{input.AbsoluteY, input.AbsoluteRY, input.AbsoluteZ, input.AbsoluteRZ} { - err = g.RegisterControlCallback(ctx, control, []input.EventType{input.PositionChangeAbs}, motorCtl) -} -``` diff --git a/docs/appendix/apis/components/motor.md b/docs/appendix/apis/components/motor.md deleted file mode 100644 index 75e8e0fe82c..00000000000 --- a/docs/appendix/apis/components/motor.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: "Motor API" -linkTitle: "Motor" -weight: 100 -type: "docs" -description: "Give commands to operate a motor or get its current status." -icon: true -images: ["/icons/components/motor.svg"] -date: "2024-10-10" -# updated: "" # When the content was last entirely checked ---- - -The motor API allows you to give commands to your [motor components](/components/motor/) for operating a motor or getting its current status. - -The motor component supports the following methods: - -{{< readfile "/static/include/components/apis/generated/motor-table.md" >}} - -## Establish a connection - -To get started using Viam's SDKs to connect to and control your motor and the rest of your machine, go to your machine's page on the [Viam app](https://app.viam.com), -Navigate to the **CONNECT** tab's **Code sample** page, select your preferred programming language, and copy the sample code. - -{{% snippet "show-secret.md" %}} - -When executed, this sample code creates a connection to your machine as a client. - -The following examples assume you have a motor called `"my_motor"` configured as a component of your machine. -If your motor has a different name, change the `name` in the code. - -Import the motor package for the SDK you are using: - -{{< tabs >}} -{{% tab name="Python" %}} - -```python -from viam.components.motor import Motor -``` - -{{% /tab %}} -{{% tab name="Go" %}} - -```go -import ( - "go.viam.com/rdk/components/motor" -) -``` - -{{% /tab %}} -{{< /tabs >}} - -## API - -{{< readfile "/static/include/components/apis/generated/motor.md" >}} diff --git a/docs/appendix/apis/components/movement-sensor.md b/docs/appendix/apis/components/movement-sensor.md deleted file mode 100644 index 4be1c5ef6dd..00000000000 --- a/docs/appendix/apis/components/movement-sensor.md +++ /dev/null @@ -1,61 +0,0 @@ ---- -title: "Movement sensor API" -linkTitle: "Movement Sensor" -weight: 110 -type: "docs" -description: "Give commands for getting the current GPS location, linear velocity and acceleration, angular velocity and acceleration and heading." -icon: true -images: ["/icons/components/imu.svg"] -date: "2022-10-10" -# updated: "" # When the content was last entirely checked ---- - -The movement sensor API allows you to give commands to your [movement sensor components](/components/movement-sensor/) for getting a GPS location, linear velocity and acceleration, angular velocity and acceleration and heading. - -Different movement sensors provide different data, so be aware that not all of the methods below are supported by all movement sensors. - -{{< alert title="Tip" color="tip" >}} -You can run `GetProperties` on your sensor for a list of its supported methods. -{{< /alert >}} - - - - -{{< readfile "/static/include/components/apis/movement-sensor.md" >}} - -## Establish a connection - -To get started using Viam's SDKs to connect to and control your movement sensor and the rest of your machine, go to your machine's page on the [Viam app](https://app.viam.com), -Navigate to the **CONNECT** tab's **Code sample** page, select your preferred programming language, and copy the sample code. - -{{% snippet "show-secret.md" %}} - -When executed, this sample code creates a connection to your machine as a client. - -The following examples assume you have a movement sensor called `"my_movement_sensor"` configured as a component of your machine. -If your movement sensor has a different name, change the `name` in the code. - -Import the movement sensor package for the SDK you are using: - -{{< tabs >}} -{{% tab name="Python" %}} - -```python -from viam.components.movement_sensor import MovementSensor -``` - -{{% /tab %}} -{{% tab name="Go" %}} - -```go -import ( - "go.viam.com/rdk/components/movementsensor" -) -``` - -{{% /tab %}} -{{< /tabs >}} - -## API - -{{< readfile "/static/include/components/apis/generated/movement_sensor.md" >}} diff --git a/docs/appendix/apis/components/power-sensor.md b/docs/appendix/apis/components/power-sensor.md deleted file mode 100644 index 0cd6ade9e48..00000000000 --- a/docs/appendix/apis/components/power-sensor.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: "Power sensor API" -linkTitle: "Power Sensor" -weight: 120 -type: "docs" -description: "Commands for getting measurements of voltage, current, and power consumption." -icon: true -images: ["/icons/components/power-sensor.svg"] -date: "2022-10-10" -# updated: "" # When the content was last entirely checked ---- - -The power sensor API allows you to give commands to your [power sensor components](/components/power-sensor/) for getting measurements of voltage, current, and power consumption. - -The power sensor component supports the following methods: - -{{< readfile "/static/include/components/apis/generated/power_sensor-table.md" >}} - -## Establish a connection - -To get started using Viam's SDKs to connect to and control your power sensor and the rest of your machine, go to your machine's page on the [Viam app](https://app.viam.com), -Navigate to the **CONNECT** tab's **Code sample** page, select your preferred programming language, and copy the sample code. - -{{% snippet "show-secret.md" %}} - -When executed, this sample code will create a connection to your machine as a client. -Once connected, you can control your machine programmatically by adding API method calls as shown in the following examples. - -The following examples assume you have a power sensor called `"my_power_sensor"` configured as a component of your machine. -If your power sensor has a different name, change the `name` in the code. - -Import the power sensor package for the SDK you are using: -{{< tabs >}} -{{% tab name="Python" %}} - -```python -from viam.components.power_sensor import PowerSensor -``` - -{{% /tab %}} -{{% tab name="Go" %}} - -```go -import ( - "go.viam.com/rdk/components/powersensor" -) -``` - -{{% /tab %}} -{{< /tabs >}} - -## API - -{{< readfile "/static/include/components/apis/generated/power_sensor.md" >}} diff --git a/docs/appendix/apis/components/sensor.md b/docs/appendix/apis/components/sensor.md deleted file mode 100644 index c28665efce2..00000000000 --- a/docs/appendix/apis/components/sensor.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: "Sensor API" -linkTitle: "Sensor" -weight: 130 -type: "docs" -description: "Commands for getting sensor readings." -icon: true -images: ["/icons/components/sensor.svg"] -date: "2022-10-10" -# updated: "" # When the content was last entirely checked ---- - -The sensor API allows you to get measurements from your [sensor components](/components/sensor/). - -The sensor component supports the following methods: - -{{< readfile "/static/include/components/apis/generated/sensor-table.md" >}} - -## Establish a connection - -To get started using Viam's SDKs to connect to and control your sensor and the rest of your machine, go to your machine's page on the [Viam app](https://app.viam.com), -Navigate to the **CONNECT** tab's **Code sample** page, select your preferred programming language, and copy the sample code. - -{{% snippet "show-secret.md" %}} - -When executed, this sample code creates a connection to your machine as a client. - -The following examples assume you have a sensor called `"my_sensor"` configured as a component of your machine. -If your sensor has a different name, change the `name` in the code. - -Import the sensor package for the SDK you are using: - -{{< tabs >}} -{{% tab name="Python" %}} - -```python -from viam.components.sensor import Sensor -``` - -{{% /tab %}} -{{% tab name="Go" %}} - -```go -import ( - "go.viam.com/rdk/components/sensor" -) -``` - -{{% /tab %}} -{{< /tabs >}} - -## API - -{{< readfile "/static/include/components/apis/generated/sensor.md" >}} diff --git a/docs/appendix/apis/components/servo.md b/docs/appendix/apis/components/servo.md deleted file mode 100644 index c586b34c98c..00000000000 --- a/docs/appendix/apis/components/servo.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: "Servo API" -linkTitle: "Servo" -weight: 140 -type: "docs" -description: "Commands for controlling the angular position of a servo precisely or getting its current status." -icon: true -images: ["/icons/components/servo.svg"] -date: "2022-10-10" -# updated: "" # When the content was last entirely checked ---- - -The servo API allows you to give commands to your [servo components](/components/servo/) for controlling the angular position of a servo precisely or getting its current status. - -The servo component supports the following methods: - -{{< readfile "/static/include/components/apis/generated/servo-table.md" >}} - -## Establish a connection - -To get started using Viam's SDKs to connect to and control your servo and the rest of your machine, go to your machine's page on the [Viam app](https://app.viam.com), -Navigate to the **CONNECT** tab's **Code sample** page, select your preferred programming language, and copy the sample code. - -{{% snippet "show-secret.md" %}} - -When executed, this sample code creates a connection to your machine as a client. - -The following examples assume you have a servo called `"my_servo"` configured as a component of your machine. -If your servo has a different name, change the `name` in the code. - -Import the servo package for the SDK you are using: - -{{< tabs >}} -{{% tab name="Python" %}} - -```python -from viam.components.servo import Servo -``` - -{{% /tab %}} -{{% tab name="Go" %}} - -```go -import ( - "go.viam.com/rdk/components/servo" -) -``` - -{{% /tab %}} -{{< /tabs >}} - -## API - -{{< readfile "/static/include/components/apis/generated/servo.md" >}} diff --git a/docs/appendix/apis/services/SLAM.md b/docs/appendix/apis/services/SLAM.md deleted file mode 100644 index 619a882b4bc..00000000000 --- a/docs/appendix/apis/services/SLAM.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: "SLAM service API" -linkTitle: "SLAM" -weight: 60 -type: "docs" -tags: ["slam", "services"] -description: "Give commands to get a machine's position within a map." -icon: true -images: ["/services/icons/slam.svg"] -date: "2022-01-01" -# updated: "" # When the content was last entirely checked ---- - -The SLAM service API allows you to get a machine's position within a map. - -The [SLAM service](/services/slam/) supports the following methods: - -{{< readfile "/static/include/services/apis/generated/slam-table.md" >}} - -## Establish a connection - -To get started using Viam's SDKs to connect to and control your machine, go to your machine's page on the [Viam app](https://app.viam.com), navigate to the **CONNECT** tab's **Code sample** page, select your preferred programming language, and copy the sample code. - -{{% snippet "show-secret.md" %}} - -When executed, this sample code creates a connection to your machine as a client. - -The following code examples assume that you have a machine configured with a SLAM service called `"my_slam_service"`. - -{{< tabs >}} -{{% tab name="Python" %}} - -```python -from viam.services.slam import SLAMClient -``` - -{{% /tab %}} -{{% tab name="Go" %}} - -```go -import ( - "go.viam.com/rdk/services/slam" -) -``` - -{{% /tab %}} -{{< /tabs >}} - -## API - -{{< readfile "/static/include/services/apis/generated/slam.md" >}} diff --git a/docs/appendix/apis/services/_index.md b/docs/appendix/apis/services/_index.md deleted file mode 100644 index fb20e2665fc..00000000000 --- a/docs/appendix/apis/services/_index.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -linkTitle: "Service APIs" -title: "Service APIs" -weight: 5 -empty_node: true -layout: "empty" -canonical: "/appendix/apis/" -type: "docs" ---- diff --git a/docs/appendix/apis/services/base-rc.md b/docs/appendix/apis/services/base-rc.md deleted file mode 100644 index 3f5970ccf1a..00000000000 --- a/docs/appendix/apis/services/base-rc.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -title: "Base Remote Control service API" -linkTitle: "Base Remote Control" -weight: 70 -type: "docs" -tags: ["base", "services", "rover", "input controller", "remote control"] -description: "Give commands to get a list of inputs from the controller that are being monitored for that control mode." -icon: true -images: ["/services/icons/base-rc.svg"] -date: "2022-01-01" -# updated: "" # When the content was last entirely checked ---- - -The base remote control service API allows you to get a list of inputs from the controller that are being monitored for that control mode. - -The [SLAM service](/services/slam/) supports the following methods: - -{{< readfile "/static/include/services/apis/generated/base_remote_control-table.md" >}} - -## Establish a connection - -To get started using Viam's SDKs to connect to and control your machine, go to your machine's page on the [Viam app](https://app.viam.com), navigate to the **CONNECT** tab's **Code sample** page, select your preferred programming language, and copy the sample code. - -{{% snippet "show-secret.md" %}} - -When executed, this sample code creates a connection to your machine as a client. - -{{< tabs >}} -{{% tab name="Go" %}} - -```go -import ( - "go.viam.com/rdk/services/baseremotecontrol" -) -``` - -{{% /tab %}} -{{< /tabs >}} - -## API - -{{< readfile "/static/include/services/apis/generated/base_remote_control.md" >}} diff --git a/docs/appendix/apis/services/data.md b/docs/appendix/apis/services/data.md deleted file mode 100644 index 2dc20cd47ed..00000000000 --- a/docs/appendix/apis/services/data.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -title: "Data Management Service API" -linkTitle: "Data Management" -weight: 10 -type: "docs" -description: "Give commands to your data management service to sync data stored on the machine it is deployed on to the cloud." -icon: true -images: ["/icons/components/arm.svg"] -date: "2022-01-01" -# updated: "" # When the content was last entirely checked ---- - -The data management service API allows you to sync data stored on the machine it is deployed on to the cloud. - -The [data management service](/services/data/) supports the following methods: - -{{< readfile "/static/include/services/apis/generated/data_manager-table.md" >}} - -The data client API supports a separate set of methods that allow you to upload and export data to and from the Viam app. -For information about that API, see [Data Client API](/appendix/apis/data-client/). - -## Establish a connection - -To get started using Viam's SDKs to connect to and control your machine, go to your machine's page on the [Viam app](https://app.viam.com), navigate to the **CONNECT** tab's **Code sample** page, select your preferred programming language, and copy the sample code. - -{{% snippet "show-secret.md" %}} - -When executed, this sample code creates a connection to your machine as a client. - -The following examples assume that you have a machine configured with an `data_manager` service. - -{{< tabs >}} -{{% tab name="Go" %}} - -```go -import ( - "go.viam.com/rdk/services/datamanager" -) -``` - -{{% /tab %}} -{{< /tabs >}} - -## API - -{{< readfile "/static/include/services/apis/generated/data_manager.md" >}} diff --git a/docs/appendix/apis/services/generic.md b/docs/appendix/apis/services/generic.md deleted file mode 100644 index 292de7b1a67..00000000000 --- a/docs/appendix/apis/services/generic.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -title: "Generic service API" -linkTitle: "Generic" -weight: 60 -type: "docs" -tags: ["generic", "services"] -description: "Give commands to your generic components for running model-specific commands using DoCommand." -icon: true -images: ["/icons/components/generic.svg"] -date: "2022-01-01" -# updated: "" # When the content was last entirely checked ---- - -The generic service API allows you to give commands to your [generic services](/services/generic/) for running model-specific commands using [`DoCommand`](/appendix/apis/services/generic/#docommand). - -The generic service supports the following methods: - -{{< readfile "/static/include/services/apis/generated/generic_service-table.md" >}} - -## Establish a connection - -To get started using Viam's SDKs to connect to and control your machine, go to your machine's page on the [Viam app](https://app.viam.com), navigate to the **CONNECT** tab's **Code sample** page, select your preferred programming language, and copy the sample code. - -{{% snippet "show-secret.md" %}} - -When executed, this sample code creates a connection to your machine as a client. - -{{< tabs >}} -{{% tab name="Python" %}} - -```python -from viam.services.generic import Generic -``` - -{{% /tab %}} -{{% tab name="Go" %}} - -```go -import ( - "go.viam.com/rdk/services/generic" -) -``` - -{{% /tab %}} -{{% tab name="C++" %}} - -```cpp -#include -``` - -{{% /tab %}} -{{< /tabs >}} - -## API - -{{< readfile "/static/include/services/apis/generated/generic_service.md" >}} diff --git a/docs/appendix/apis/services/ml.md b/docs/appendix/apis/services/ml.md deleted file mode 100644 index bea271dcb53..00000000000 --- a/docs/appendix/apis/services/ml.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -title: "ML model service API" -linkTitle: "ML Model" -weight: 30 -type: "docs" -tags: ["data management", "ml", "model training"] -description: "Give commands to your ML model service to make inferences based on a provided ML model." -icon: true -images: ["/services/icons/ml.svg"] -date: "2022-01-01" -# updated: "" # When the content was last entirely checked ---- - -The ML model service API allows you to make inferences based on a provided ML model. - -The [ML Model service](/services/ml/) supports the following methods: - -{{< readfile "/static/include/services/apis/generated/mlmodel-table.md" >}} - -## Establish a connection - -{{< alert title="Viam Python SDK Support" color="note" >}} - -To use the ML model service from the [Viam Python SDK](https://python.viam.dev/), install the Python SDK using the `mlmodel` extra: - -```sh {class="command-line" data-prompt="$"} -pip install 'viam-sdk[mlmodel]' -``` - -{{< /alert >}} - -To get started using Viam's SDKs to connect to and control your machine, go to your machine's page on the [Viam app](https://app.viam.com), navigate to the **CONNECT** tab's **Code sample** page, select your preferred programming language, and copy the sample code. - -{{% snippet "show-secret.md" %}} - -When executed, this sample code creates a connection to your machine as a client. - -The following examples assume that you have a machine configured with an `MLModel` service called `"my_mlmodel_service"`, and that you have installed the `mlmodel` extra for the Python SDK. -If your ML model service has a different name, change the `name` in the code. - -Import the mlmodel package for the SDK you are using: - -{{< tabs >}} -{{% tab name="Python" %}} - -```python -from viam.services.mlmodel import MLModelClient -``` - -{{% /tab %}} -{{% tab name="Go" %}} - -```go -import ( - "go.viam.com/rdk/services/mlmodel" -) -``` - -{{% /tab %}} -{{< /tabs >}} - -## API - -{{< readfile "/static/include/services/apis/generated/mlmodel.md" >}} diff --git a/docs/appendix/apis/services/motion.md b/docs/appendix/apis/services/motion.md deleted file mode 100644 index cce2557dece..00000000000 --- a/docs/appendix/apis/services/motion.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: "Motion Service API" -linkTitle: "Motion" -weight: 40 -type: "docs" -description: "Give commands to move a machine based on a SLAM map or GPS coordinates or to move a machine's components form one location to another." -icon: true -images: ["/icons/components/arm.svg"] -date: "2022-01-01" -# updated: "" # When the content was last entirely checked ---- - -The motion service API allows you to give commands to your [motion service](/services/motion/) for moving a machine based on a SLAM map or GPS coordinates or for moving a machine's components from one location to another. - -The motion service supports the following methods: - -{{< readfile "/static/include/services/apis/generated/motion-table.md" >}} - -## Establish a connection - -To get started using Viam's SDKs to connect to and control your machine, go to your machine's page on the [Viam app](https://app.viam.com), navigate to the **CONNECT** tab's **Code sample** page, select your preferred programming language, and copy the sample code. - -{{% snippet "show-secret.md" %}} - -When executed, this sample code creates a connection to your machine as a client. - -Because the motion service is enabled by default, you don't give it a `"name"` while configuring it. -Use the name `"builtin"` to access the built-in motion service in your code with methods like [`FromRobot()`](/appendix/apis/services/motion/#fromrobot) that require a `ResourceName`. - -Import the motion package for the SDK you are using: - -{{< tabs >}} -{{% tab name="Python" %}} - -```python -from viam.services.motion import MotionClient -``` - -{{% /tab %}} -{{% tab name="Go" %}} - -```go -import ( - "go.viam.com/rdk/services/motion" -) -``` - -{{% /tab %}} -{{< /tabs >}} - -## API - -{{< readfile "/static/include/services/apis/generated/motion.md" >}} diff --git a/docs/appendix/apis/services/navigation.md b/docs/appendix/apis/services/navigation.md deleted file mode 100644 index 558c9d18e0b..00000000000 --- a/docs/appendix/apis/services/navigation.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: "Navigation service API" -linkTitle: "Navigation" -weight: 50 -type: "docs" -tags: ["navigation", "services", "base", "rover"] -description: "Give commands to define waypoints and move your machine along those waypoints while avoiding obstacles." -icon: true -images: ["/services/icons/navigation.svg"] -date: "2022-01-01" -# updated: "" # When the content was last entirely checked ---- - -The navigation service API allows you to define waypoints and move your machine along those waypoints while avoiding obstacles. - -The [navigation service](/services/navigation/) supports the following methods: - -{{< readfile "/static/include/services/apis/generated/navigation-table.md" >}} - -## Establish a connection - -To get started using Viam's SDKs to connect to and control your machine, go to your machine's page on the [Viam app](https://app.viam.com), navigate to the **CONNECT** tab's **Code sample** page, select your preferred programming language, and copy the sample code. - -{{% snippet "show-secret.md" %}} - -When executed, this sample code creates a connection to your machine as a client. - -The following code examples assume that you have a machine configured with a `Navigation` service. - -{{< tabs >}} -{{% tab name="Python" %}} - -```python -from viam.services.navigation import NavigationClient -``` - -{{% /tab %}} -{{% tab name="Go" %}} - -```go -import ( - "go.viam.com/rdk/services/navigation" -) -``` - -{{% /tab %}} -{{< /tabs >}} - -## API - -{{< readfile "/static/include/services/apis/generated/navigation.md" >}} diff --git a/docs/appendix/apis/services/vision.md b/docs/appendix/apis/services/vision.md deleted file mode 100644 index 272129784c1..00000000000 --- a/docs/appendix/apis/services/vision.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -title: "Vision service API" -linkTitle: "Vision" -weight: 20 -type: "docs" -tags: ["vision", "computer vision", "CV", "services"] -description: "Give commands to get detections, classifications, or point cloud objects, depending on the ML model the vision service is using." -icon: true -images: ["/services/icons/vision.svg"] -tags: ["vision", "computer vision", "CV", "services"] -date: "2022-01-01" -# updated: "" # When the content was last entirely checked ---- - -The vision service API allows you to get detections, classifications, or point cloud objects, depending on the ML model the vision service is using. - -The [vision service](/services/vision/) supports the following methods: - -{{< readfile "/static/include/services/apis/generated/vision-table.md" >}} - -## Establish a connection - -To get started using Viam's SDKs to connect to and control your machine, go to your machine's page on the [Viam app](https://app.viam.com), navigate to the **CONNECT** tab's **Code sample** page, select your preferred programming language, and copy the sample code. - -{{% snippet "show-secret.md" %}} - -When executed, this sample code creates a connection to your machine as a client. - -The following examples assume that you have a machine configured with a [camera](/components/camera/) and a vision service [detector](/services/vision/#detections), [classifier](/services/vision/#classifications) or [segmenter](/services/vision/#segmentations). - -{{< tabs >}} -{{% tab name="Python" %}} - -```python -from viam.services.vision import VisionClient -``` - -{{% /tab %}} -{{% tab name="Go" %}} - -```go -import ( - "go.viam.com/rdk/services/vision" -) -``` - -{{% /tab %}} -{{< /tabs >}} - -## API - -{{< readfile "/static/include/services/apis/generated/vision.md" >}} diff --git a/docs/appendix/changelog.md b/docs/appendix/changelog.md deleted file mode 100644 index 50acc90a32e..00000000000 --- a/docs/appendix/changelog.md +++ /dev/null @@ -1,1229 +0,0 @@ ---- -title: "Changelog" -linkTitle: "Changelog" -weight: 20 -draft: false -type: "docs" -description: "A log of added features, improvements, and changes over time." -aliases: - - "/appendix/release-notes/" - - "/components/camera/single-stream/" - - "/components/camera/dual-stream/" - - "/components/camera/align-color-depth-extrinsics/" - - "/components/camera/align-color-depth-homography/" - - "/components/board/customlinux/" - - "/components/board/jetson/" - - "/components/board/pca9685/" - - "/components/board/ti/" - - "/components/gripper/softrobotics/" - - "/components/motor/encoded-motor/" - - "/components/motor/gpiostepper/" - - "/components/motor/roboclaw/" - - "/components/movement-sensor/adxl345/" - - "/components/movement-sensor/dual-gps-rtk/" - - "/components/movement-sensor/gps-nmea-rtk-pmtk/" - - "/components/movement-sensor/gps-nmea-rtk-serial/" - - "/components/movement-sensor/gps-nmea/" - - "/components/movement-sensor/wheeled-odometry/" - - "/components/power-sensor/ina219/" - - "/components/power-sensor/ina226/" - - "/components/sensor/bme280/" - - "/components/sensor/ds18b20/" - - "/components/sensor/sensirion-sht3xd/" -layout: "changelog" -outputs: - - rss - - html -date: "2024-09-18" -# updated: "" # When the content was last entirely checked ---- - - - -{{% changelog date="2024-11-12" color="added" title="Builtin models moved to modules" %}} - -The following resource models have moved to modules. - - -| Resource | Model | -| -------- | ----- | -| board | [`customlinux`](https://github.com/viam-modules/customlinux/) | -| board | [`jetson`](https://github.com/viam-modules/nvidia) | -| board | [`pca9685`](https://github.com/viam-modules/pca/tree/main) | -| board | [`odroid`](https://github.com/viam-modules/hardkernel) | -| board | [`ti`](https://github.com/viam-modules/texas-instruments) | -| board | [`pi`](https://github.com/viam-modules/raspberry-pi) | -| board | [`orange-pi`](https://github.com/viam-modules/orange-pi) | -| board | [`upboard`](https://github.com/viam-modules/up) | -| motor | [`tmc5072`](https://github.com/viam-modules/analog-devices) | -| motor | [`28byj-48`](https://github.com/viam-modules/uln2003) | -| encoder | [`ams-as5048`](https://github.com/viam-modules/ams/) | -| movement sensor | [`adxl345`](https://github.com/viam-modules/analog-devices) | -| movement sensor | [`dual-gps-rtk`](https://github.com/viam-modules/gps/) | -| movement sensor | [`gps-nmea-rtk-pmtk`](https://github.com/viam-modules/gps/) | -| movement sensor | [`gps-nmea-rtk-serial`](https://github.com/viam-modules/gps/) | -| movement sensor | [`gps-nmea`](https://github.com/viam-modules/gps/) | -| movement sensor | [`imu-wit`](https://github.com/viam-modules/wit-motion) | -| movement sensor | [`imu-wit-hwt905`](https://github.com/viam-modules/wit-motion) | -| movement sensor | [`mpu6050`](https://github.com/viam-modules/tdk-invensense) | -| power sensor | [`ina219`](https://github.com/viam-modules/texas-instruments) | -| power sensor | [`ina226`](https://github.com/viam-modules/texas-instruments) | -| sensor | [`bme280`](https://github.com/viam-modules/bosch) | -| sensor | [`sensirion-sht3xd`](https://github.com/viam-modules/sensirion) | -| sensor | [`pi`](https://github.com/viam-modules/raspberry-pi) | -| ML model | [`TFLite CPU`](https://app.viam.com/module/viam/tflite_cpu) | - -The following models were removed: - - -| Resource | Model | -| -------- | ----- | -| gripper | `softrobotics` | -| motor | `encoded-motor` | -| motor | `gpiostepper` | -| motor | `roboclaw` | -| sensor | `ds18b20` | - -{{% /changelog %}} - -{{% changelog date="2024-11-05" color="added" title="MoveThroughJointPositions to arm interface" %}} -The [arm interface](/appendix/apis/components/arm/) now includes a [MoveThroughJointPositions](https://pkg.go.dev/go.viam.com/rdk/components/arm#Arm) method that moves an arm through an ordered array of joint positions. -{{% /changelog %}} - -{{% changelog date="2024-10-16" color="added" title="Set data retention policies" %}} - -You can now set how long data collected by a component should remain stored in the Viam Cloud in the component's data capture configuration. -For more information, see [Data management service](/services/data/). - -{{% /changelog %}} - -{{% changelog date="2024-09-20" color="added" title="Pi models moved to module" %}} - -The Raspberry Pi 4, 3, and Zero 2 W boards are now supported by [`viam:raspberry-pi:rpi`](https://github.com/viam-modules/raspberry-pi). - -{{% /changelog %}} - -{{% changelog date="2024-08-26" color="added" title="ESP32 cameras" %}} - -`viam-micro-server` now supports cameras on ESP32s. -For more information, see [Configure an esp32-camera](/components/camera/esp32-camera/). - -{{% /changelog %}} - -{{% changelog date="2024-08-26" color="changed" title="Micro-RDK now called viam-micro-server" %}} - -The lightweight version of `viam-server` that is built from the micro-RDK is now referred to as `viam-micro-server`. -For more information, see [viam-micro-server](/architecture/viam-micro-server/). - -{{% /changelog %}} - -{{% changelog date="2024-08-26" color="added" title="Provisioning" %}} - -You can now configure provisioning for machines with the Viam Agent. -For more information, see [Configure provisioning with viam-agent](/how-tos/provision-setup/). - -{{% /changelog %}} - -{{% changelog date="2024-08-16" color="added" title="Data capture for vision" %}} - -Data capture is now possible for the vision service. -For more information, see [Supported components and services](/services/data/#supported-components-and-services). - -{{% /changelog %}} - -{{% changelog date="2024-08-01" color="added" title="Create custom training scripts" %}} - -You can now upload custom training scripts to the Viam Registry and use them to train machine learning models. -For more information, see [Create custom training scripts](/how-tos/create-custom-training-scripts/). - -{{% /changelog %}} - -{{% changelog date="2024-07-19" color="changed" title="Operators can now view data" %}} - -The operator role now has view permissions for the data in the respective resource a user has access to. -For more information, see [Data and machine learning permissions](/cloud/rbac/#data-and-machine-learning). - -{{% /changelog %}} - -{{% changelog date="2024-06-14" color="changed" title="Python get_robot_part_logs parameters" %}} - -The `errors_only` parameter has been removed from [`get_robot_part_logs()`](/appendix/apis/fleet/#getrobotpartlogs) and replaced with `log_levels`. - -{{% /changelog %}} - -{{% changelog date="2024-05-28" color="changed" title="Return type of analog Read" %}} - -The board analog API [`Read()`](/appendix/apis/components/board/#readanalogreader) method now returns an `AnalogValue` struct instead of a single int. -The struct contains an int representing the value of the reading, min and max range of values, and the precision of the reading. - -{{% /changelog %}} - -{{% changelog date="2024-05-28" color="added" title="CaptureAllFromCamera and GetProperties to vision API" %}} - -The vision service now supports two new methods: [`CaptureAllFromCamera`](/appendix/apis/services/vision/#captureallfromcamera) and [`GetProperties`](/appendix/apis/services/vision/#getproperties). - -{{% /changelog %}} - -{{% changelog date="2024-05-14" color="changed" title="Renamed GeoObstacle to GeoGeometry" %}} - -The motion service API parameter `GeoObstacle` has been renamed to `GeoGeometry`. -This affects users of the [`MoveOnGlobe()`](/appendix/apis/services/motion/#moveonglobe) method. - -{{% /changelog %}} - -{{< changelog date="2024-05-09" color="changed" title="Return type of GetImage" >}} - -The Python SDK introduced a new image container class called [`ViamImage`](https://python.viam.dev/autoapi/viam/components/camera/index.html#viam.components.camera.ViamImage). -The camera component's [`GetImage()`](/appendix/apis/components/camera/#getimage) method now returns a `ViamImage` type, and the vision service's [`GetDetections()`](/appendix/apis/services/vision/#getdetections) and [`GetClassifications()`](/appendix/apis/services/vision/#getclassifications) methods take in `ViamImage` as a parameter. - -You can use the helper functions `viam_to_pil_image` and `pil_to_viam_image` provided by the Python SDK to convert the `ViamImage` into a [`PIL Image`](https://omz-software.com/pythonista/docs/ios/Image.html) and vice versa. - -{{< expand "Click for an example of using the ViamImage -> PIL Image helper functions." >}} - -```python {class="line-numbers linkable-line-numbers"} -from viam.media.utils.pil import pil_to_viam_image, viam_to_pil_image - -# Get the ViamImage from your camera. -frame = await my_camera.get_image() - -# Convert "frame" to a PIL Image representation. -pil_frame = viam_to_pil_image(frame) - -# Use methods from the PIL Image class to get size. -x, y = pil_frame.size[0], pil_frame.size[1] -# Crop image to get only the left two fifths of the original image. -cropped_pil_frame = pil_frame.crop((0, 0, x / 2.5, y)) - -# Convert back to ViamImage. -cropped_frame = pil_to_viam_image(cropped_pil_frame) - -# Get detections from your vision service. -detections = await detector.get_detections(cropped_frame) -``` - -{{< /expand >}} -{{< /changelog >}} - -{{% changelog date="2024-05-08" color="removed" title="WriteAnalog from Go SDK" %}} - -The `WriteAnalog()` method has been removed from the Go SDK. -Use [`AnalogByName()`](/appendix/apis/components/board/#analogbyname) followed by [`Write()`](/appendix/apis/components/board/#writeanalog) instead. - -{{% /changelog %}} - -{{% changelog date="2024-04-30" color="changed" title="Python SDK data retrieval behavior" %}} - -[`tabular_data_by_filter()`](/appendix/apis/data-client/#tabulardatabyfilter) and [`binary_data_by_filter()`](/appendix/apis/data-client/#binarydatabyfilter) now return paginated data. - -{{% /changelog %}} - -{{% changelog date="2024-04-30" color="changed" title="Renamed AnalogReader to Analog" %}} - -`AnalogReader` has been renamed to `Analog`. -The functionality remains the same, but code that uses analogs must be updated. -`AnalogReaderByName()` and `AnalogReaderNames()` have become [`AnalogByName()`](/appendix/apis/components/board/#analogbyname) and `AnalogNames()` (since deprecated), respectively. - -{{% /changelog %}} - -{{% changelog date="2024-04-30" color="added" title="Part online and part offline triggers" %}} - -You can now configure [triggers](/configure/triggers/) to execute actions when a {{< glossary_tooltip term_id="part" text="machine part" >}} comes online or goes offline. - -{{% /changelog %}} - -{{% changelog date="2024-04-30" color="removed" title="Status from Board API" %}} - -Viam has removed support for the following board API methods: `Status()`, `AnalogStatus()`, `DigitalInterruptStatus()`, `Close()`, `Tick()`, `AddCallback()`, and `RemoveCallback()`. - -{{% /changelog %}} - -{{% changelog date="2024-04-19" color="removed" title="Removed and replaced camera models" %}} - -Viam has removed support for following builtin camera models: `single_stream`, `dual_stream`, `align_color_depth_extrinsics`, and `align_color_depth_homography`. - -{{% /changelog %}} - -{{% changelog date="2024-04-17" color="changed" title="Updated GetCloudMetadata response" %}} - -In addition to the existing returned metadata, the [`GetCloudMetadata`](/appendix/apis/robot/#getcloudmetadata) method now returns `machine_id` and `machine_part_id` as well. - -{{% /changelog %}} - -{{% changelog date="2024-04-16" color="improved" title="Viam app interface" %}} - -the [Viam app](https://app.viam.com) machine page UI has been updated significantly. -In addition to other improvements, your component, service, and other resource config cards are all displayed on one page instead of in separate tabs. - -{{% /changelog %}} - -{{% changelog date="2024-03-01" color="added" title="Additional ML models" %}} - -Viam has added support for the TensorFlow, PyTorch, and ONNX ML model frameworks, expanding upon the existing support for TensorFlow Lite models. -You can now upload your own ML model(/registry/ml-models/) using any of these frameworks for use with the Vision service. - -{{% /changelog %}} - -{{% changelog date="2024-03-01" color="added" title="Ultrasonic sensor for `viam-micro-server`" %}} - -You can now use the [ultrasonic sensor component](/components/sensor/ultrasonic-micro-rdk/) with [`viam-micro-server`](/installation/viam-micro-server-setup/#install-viam-micro-server) to integrate an [HC-S204](https://www.sparkfun.com/products/15569) ultrasonic distance sensor into a machine running `viam-micro-server`. - -{{% /changelog %}} - -{{% changelog date="2024-03-01" color="added" title="Edit a machine configuration that uses a fragment" %}} - -You can now edit the configuration of an existing machine that has been configured with a fragment by using [the `fragment_mods` object](/fleet/fragments/#modify-the-config-of-a-machine-that-uses-a-fragment) in your configuration. -You can use the `fragment_mods` objects to be able to deploy a fragment to a fleet of machines, but still be able to make additional per-machine edits as needed. - -{{% /changelog %}} - -{{% changelog date="2024-03-01" color="added" title="Dual GPS movement sensor" %}} - -You can now use the [dual GPS movement sensor component](https://github.com/viam-modules/gps) to integrate a movement sensor that employs two GPS sensors into your machine. -The dual GPS movement sensor calculates a compass heading from both GPS sensors, and returns the midpoint position between the two sensors as its position. - -{{% /changelog %}} - -{{% changelog date="2024-03-01" color="added" title="Viam Agent" %}} - -You can now use the [Viam Agent](/fleet/provision/) to provision your machine or fleet of machines during deployment. -The Viam Agent is a software provisioning manager that you can install on your machine which manages your `viam-server` installation, including installation and ongoing updates, as well as providing flexible deployment configuration options, such as pre-configured WiFi network credentials. - -{{% /changelog %}} - -{{% changelog date="2024-02-12" color="added" title="Generic service" %}} - -You can now use the [generic service](/services/generic/) to define new, unique types of services that do not already have an [appropriate API](/appendix/apis/#service-apis) defined for them. - -{{% /changelog %}} - -{{% changelog date="2024-02-12" color="added" title="ML models in the registry" %}} - -You can now upload [machine learning (ML) models](/registry/ml-models/) to the Viam Registry, in addition to modules. -You may upload models you have trained yourself using the Viam app, or models you have trained outside of the App. -When uploading, you have the option to make your model available to the general public for reuse. - -{{% /changelog %}} - -{{% changelog date="2024-01-31" color="added" title="Sensor-controlled base" %}} - -Viam has added a [sensor-controlled base](/components/base/sensor-controlled/) component model, which supports a robotic base that receives feedback control from a movement sensor. - -{{% /changelog %}} - -{{% changelog date="2024-01-31" color="added" title="Visualize captured data" %}} - -You can now [visualize your data](/how-tos/sensor-data-visualize/) using many popular third-party visualization tools, including Grafana, Tableau, Google’s Looker Studio, and more. -You can visualize any data, such as sensor readings, that you have [synced](/services/data/) to the Viam app from your machine. - -See [Visualize data with Grafana](/tutorials/services/visualize-data-grafana/) for a full walkthrough focused on Grafana specifically. - -{{% /changelog %}} - -{{% changelog date="2024-01-31" color="added" title="Use triggers to trigger actions" %}} - -You can now configure [triggers](/configure/triggers/) (previously called webhooks) to execute actions when certain types of data are sent from your machine to the cloud. - -{{% /changelog %}} - -{{% changelog date="2023-12-31" color="added" title="Filtered camera module" %}} - -Viam has added a [`filtered-camera` module](https://app.viam.com/module/erh/filtered-camera) that selectively captures and syncs only the images that match the detections of an ML model. -For example, you could train an ML model that is focused on sports cars, and only capture images from the camera feed when a sports car is detected in the frame. - -Check out [this guide](/how-tos/image-data/) for more information. - -{{% /changelog %}} - -{{% changelog date="2023-12-31" color="added" title="Raspberry Pi 5 Support" %}} - -You can now run `viam-server` on a [Raspberry Pi 5](/components/board/pi5/) with the new board model [`pi5`](/components/board/pi5/). - -{{% /changelog %}} - -{{% changelog date="2023-12-31" color="added" title="Role-based access control" %}} - -Users can now have [access to different fleet management capabilities](/cloud/rbac/) depending on whether they are an owner or an operator of a given organization, location, or machine. - -{{% /changelog %}} - -{{% changelog date="2023-11-30" color="added" title="Authenticate with location API key" %}} - -You can now use [API keys for authentication](/sdks/#authentication). -API keys allow you to assign the minimum required permissions for usage. -Location secrets, the previous method of authentication, is deprecated and will be removed in a future release. - -{{% /changelog %}} - -{{% changelog date="2023-11-30" color="added" title="Queryable sensor data" %}} - -Once you have added the data management service and synced data, such as sensor readings, to the Viam app, you can now run queries against both captured data as well as its metadata using either SQL or MQL. - -For more information, see [Query Data with SQL or MQL](/how-tos/sensor-data-query-with-third-party-tools/). - -{{% /changelog %}} - -{{% changelog date="2023-11-30" color="changed" title="Model training from datasets" %}} - -To make it easier to iterate while training machine learning models from image data, you now train models from [datasets](/fleet/dataset/). - -{{% /changelog %}} - -{{% changelog date="2023-11-30" color="improved" title="Manage users access" %}} - -You can now manage users access to machines, locations, and organizations. -For more information, see [Access Control](/cloud/rbac/) - -{{% /changelog %}} - -{{% changelog date="2023-10-31" color="added" title="Test an ML model in browser" %}} - -After you upload and train a machine learning model, you can test its results in the **Data** tab. - -This allows you to refine models by iteratively tagging more images for training based on observed performance. - -For more information, see [Test classification models with existing images in the cloud](/services/vision/mlmodel/#existing-images-in-the-cloud). - -To use this update, the classifier must have been trained or uploaded after September 19, 2023. -The current version of this feature exclusively supports classification models. - -{{% /changelog %}} - -{{% changelog date="2023-10-31" color="added" title="PLC support" %}} - -The Viam platform now supports the [Revolution Pi line of PLCs](https://revolutionpi.com/) from KUNBUS in the form of a [module](https://app.viam.com/module/viam-labs/viam-revolution-pi). -This collaboration allows you to leverage the Raspberry Pi-based Revolution Pi, which runs on Linux and has a [specially designed I/O modules](https://www.raspberrypi.com/products/compute-module-4/?variant=raspberry-pi-cm4001000) for streamlined interaction with industrial controls, eliminating the need for additional components. - -Read the [Viam PLC Support](https://www.viam.com/post/viam-plc-support-democratizing-access-to-smart-ot-and-ics) blog post for a step-by-step guide on using a PLC with Viam. - -{{% /changelog %}} - -{{% changelog date="2023-10-31" color="improved" title="SLAM map creation" %}} - -The [Cartographer-module](/services/slam/cartographer/) now runs in Viam's cloud for creating or updating maps. -This enhancement allows you to: - -- Generate larger maps without encountering session timeouts -- Provide IMU input to improve map quality -- Save maps to the **SLAM library** -- Create or update maps using previously captured LiDAR and IMU data -- Deploy maps to machines - -{{% /changelog %}} - -{{% changelog date="2023-09-30" color="added" title="Modular registry" %}} - -The [Modular Registry](/registry/) enables you to use, create, and share custom modules, extending the capabilities of Viam beyond the components and services that are natively supported. - -You can: - -- Publish modules on the registry -- Add modules to any machine's configuration with a few clicks -- Select the desired module version for deployment, make changes at your convenience, and deploy the updates to a single machine or an entire fleet. - -{{% /changelog %}} - -{{% changelog date="2023-09-30" color="added" title="Mobile app" %}} - -You can use a [mobile application](/fleet/control/#control-interface-in-the-viam-mobile-app), available for download now in the [Apple](https://apps.apple.com/us/app/viam-robotics/id6451424162) and [Google Play](https://play.google.com/store/apps/details?id=com.viam.viammobile&hl=en&gl=US) app stores, to connect to and control your Viam-powered machines directly from your mobile device. - -{{% /changelog %}} - -{{% changelog date="2023-09-30" color="added" title="Power sensor component" %}} - -You now have the capability to use a [power sensor component](/components/power-sensor/) to monitor the voltage, current, and power consumption within your machine's system. - -{{% /changelog %}} - -{{% changelog date="2023-09-30" color="added" title="Filter component’s data before the cloud" %}} -Viam has written a module that allows you to filter data based on specific criteria before syncing it to [Viam's cloud](/services/data/). -It equips machines to: - -- Remove data that is not of interest -- Facilitate high-interval captures while saving data based on your defined metrics -- Prevent the upload of unnecessary data - -To learn more, see [this tutorial](/tutorials/configure/pet-photographer/) on creating and configuring a data filtration module. - -{{% /changelog %}} - -{{% changelog date="2023-08-31" color="added" title="Configure a custom Linux board" %}} - -You can now use boards like the [Mediatek Genio 500 Pumpkin](https://ologicinc.com/portfolio/mediateki500/) that run Linux operating systems with the [`customlinux` board model](https://github.com/viam-modules/customlinux/). - -{{% /changelog %}} - -{{% changelog date="2023-08-31" color="improved" title="Image inspection for ML training" %}} - -This update enables you to get a closer examination of your image and streamline your image annotation experience by making it easier to add bounding boxes and labels in the **Data** tab. - -With the latest improvements, you can now: - -- Navigate between images using the arrow keys in the main image view -- Expand images for a more detailed inspection by clicking the expand button on the right image panel -- Move between full-screen images effortlessly with the <> arrow buttons or arrow keys -- Return to the standard view by using the escape key or collapse button - -{{% /changelog %}} - -{{% changelog date="2023-08-31" color="added" title="Duplicate component button" %}} - -You now have the ability to duplicate any config component, service, module, remote, or process. - -To use this feature: - -- Click on the duplicate component icon at the top right of any resource -- Optionally, you can modify the component name to distinguish it -- Adjust any attributes, such as motor pin numbers - -{{% /changelog %}} - -{{% changelog date="2023-07-31" color="added" title="Apple SSO authentication" %}} - -Viam now supports sign-up/log-in through Apple Single Sign-On. - -Note that currently, accounts from different SSO providers are treated separately, with no account merging functionality. - -{{% /changelog %}} - -{{% changelog date="2023-07-31" color="improved" title="Arm component API" %}} - -Arm models now support the [`GetKinematics` method](/appendix/apis/components/arm/#getkinematics) in the arm API, allowing you to request and receive kinematic information. - -{{% /changelog %}} - -{{% changelog date="2023-06-30" color="added" title="View sensor data within Viam" %}} - -You can now [view your sensor data](https://app.viam.com/data/view?view=sensors) directly in the Viam app to verify data creation and accuracy. -If you depend on sensor data to plan and control machine operations, this feature increases access to data and supports a more efficient workflow. - -{{% /changelog %}} - -{{% changelog date="2023-06-30" color="added" title="Session management in the Python SDK" %}} - -The Python SDK now includes sessions, a safety feature that automatically cancels operations if the client loses connection to your machine. - -[Session management](/appendix/apis/sessions/) helps you to ensure safer operation of your machine when dealing with actuating controls. -Sessions are enabled by default, with the option to [disable sessions](/appendix/apis/sessions/#disable-default-session-management). - -{{% /changelog %}} - -{{% changelog date="2023-06-30" color="added" title="Connect an ODrive motor controller as a Viam module" %}} - -You can integrate and control ODrive motor controllers with Viam using the [`odrive` module from the Viam Registry](https://github.com/viamrobotics/odrive). - -See the [Odrive module readme](https://github.com/viamrobotics/odrive) to learn how to connect and use an ODrive motor controller with Viam, and view the sample configurations. - -{{% /changelog %}} - -{{% changelog date="2023-06-30" color="added" title="Implement custom robotic arms as Viam modules" %}} - -When prototyping a robotic arm, you can now facilitate movement without creating your own motion planning. -This update enables you to implement custom models of an arm component as a [modular resource](/registry/) by coding three endpoints of the [Arm API](/appendix/apis/components/arm/#api): - -- `getJointPositions` -- `movetoJointPositions` -- `GetKinematics` - -Then, use the [motion planning service](/services/motion/) to specify poses, and Viam handles the rest. - -For more information, see this [tutorial on creating a custom arm](/registry/examples/custom-arm/). - -{{% /changelog %}} - -{{% changelog date="2023-06-30" color="added" title="Apply a crop transform to camera views" %}} - -You can now apply a [crop transform](/components/camera/transform/) to the views of your connected cameras in the Viam app. - -This feature enables you to focus on a specific area of your camera feed. - -For example, crop a video stream of a busy street to just the sidewalk. - -{{% /changelog %}} - -{{% changelog date="2023-06-30" color="improved" title="Gantry component" %}} - -To better control gantries with Viam, you can now: - -- Specify speed values when calling the `MovetoPosition` method on [Gantry components](/components/gantry/). - This allows you to define the speed at which each axis moves to the desired position, providing enhanced precision and control over the gantry's movement. -- Set a home position for Gantry components to facilitate position resetting or maintain consistent starting points. - -{{% /changelog %}} - -{{% changelog date="2023-06-30" color="improved" title="Optimized Viam-trained object detection models" %}} - -This update for object detection models [trained with the machine learning service](/how-tos/train-deploy-ml/) brings significant improvements, including: - -- 76% faster model inference for camera streams -- 64% quicker model training for object detection -- 46% reduction in compressed model size - -{{% /changelog %}} - -{{% changelog date="2023-05-31" color="added" title="TypeScript SDK beta release" %}} - -The beta release of the [TypeScript SDK](https://github.com/viamrobotics/viam-typescript-sdk/) allows you to create a web interface to work with your machine, as well as create custom components and services. - -{{% /changelog %}} - -{{% changelog date="2023-05-31" color="added" title="Train object detection ML models" %}} - -You now have the capability to directly [train object detection models](/how-tos/train-deploy-ml/) in addition to image classification models from within the Viam app. - -This update allows you to: - -- Add labels by drawing bounding boxes around specific objects in your images or a single image. -- Create a curated subset of data for training by filtering images based on labels or tags. - -{{% /changelog %}} - -{{% changelog date="2023-05-31" color="added" title="Permissions for organizations in Viam" %}} - -Now when you invite collaborators to join your organization, you can assign permissions to members by setting one of these roles: - -- **Owner**: These members can see and edit [every tab on the machine page](/cloud/machines/#navigating-the-machine-page), as well as manage users in the app. - This role is best for those on your team who are actively engineering and building machines. - -- **Operator**: These members can only see and use the [remote control tab](/fleet/control/). - This role is best for those on your team who are teleoperating or remotely controlling machines. - -For more information about assigning permissions and collaborating with others on Viam, see [Fleet Management](/fleet/). - -{{% /changelog %}} - -{{% changelog date="2023-05-31" color="improved" title="Control RoboClaw motor controllers with the driver" %}} - -When using a RoboClaw motor controller without encoders connected to your motors, you now have more direct control over the RoboClaw’s functionality within Viam or through the motor API. - -For example, in the Viam app, you can now set **Go For** values for these motors, utilizing a time-based estimation for the number of revolutions. - -{{% /changelog %}} - -{{% changelog date="2023-05-31" color="improved" title="Camera webcam names and setting framerates" %}} - -The updates to the camera component have improved the process of connecting to and using cameras with your machines. - -The latest updates enable you to: - -- View readable webcam names in the **video path** of your camera component. -- Specify your preferred framerate by selecting the desired value in the newly added **framerate field** on the **CONFIGURE** tab. - -{{% /changelog %}} - -{{% changelog date="2023-05-31" color="improved" title="Additions to code samples in the Viam app" %}} - -The updated code samples now includes: - -- Options for C++ and TypeScript -- The ability to hide or display your machines' [secrets](/appendix/apis/) - -Access these samples in the **Code sample** tab on your machine's page to connect to your machine in various languages. - -{{% /changelog %}} - -{{% changelog date="2023-05-31" color="improved" title="Delete data in bulk in the Viam app" %}} - -You can manage the data synced to Viam's cloud with the new capability for bulk data deletion on the **Data** tab. - -{{% /changelog %}} - -{{% changelog date="2023-04-25" color="changed" title="Vision service" %}} - -{{% alert title="Important: Breaking Change" color="note" %}} - -The [vision service](/services/vision/) became more modular in RDK [v0.2.36](https://github.com/viamrobotics/rdk/releases/tag/v0.2.36), API [v0.1.118](https://github.com/viamrobotics/api/releases/tag/v0.1.118), and Python SDK [v0.2.18](https://github.com/viamrobotics/viam-python-sdk/releases/tag/v0.2.18). - -Find more information on each of the changes below. - -{{% /alert %}} - - - -#### Use individual vision service instances - -You need to create **an individual vision service instance** for each detector, classifier, and segmenter model. -You can no longer be able to create one vision service and register all of your detectors, classifiers, and segmenters within it. - -{{%expand "Click for details on how to migrate your code." %}} - -#### API calls - -Change your existing API calls to get the new vision service instance for your detector, classifier, or segmenter model directly from the `VisionClient`: - -{{< tabs >}} -{{% tab name="New Way" %}} - -Change your existing API calls to get the new vision service instance for your detector, classifier, or segmenter model directly from the `VisionClient`: - -```python {class="line-numbers linkable-line-numbers"} -my_object_detector = VisionClient.from_robot(robot, "find_objects") -img = await cam.get_image() -detections = await my_object_detector.get_detections(img) -``` - -{{% /tab %}} -{{% tab name="Old Way" %}} - -```python {class="line-numbers linkable-line-numbers"} -vision = VisionServiceClient.from_robot(robot) -img = await cam.get_image() -detections = await vision.get_detections(img, "find_objects") -``` - -{{% /tab %}} -{{< /tabs >}} - -#### Color detector configurations - -You can replace existing color detectors by [configuring new ones in the UI](/services/vision/color_detector/) or you can update the [JSON configuration of your machines](/configure/#the-configure-tab): - -{{< tabs >}} -{{% tab name="New Way" %}} - -```json -"services": [ - { - "name": "blue_square", - "type": "vision", - "model": "color_detector", - "attributes": { - "segment_size_px": 100, - "detect_color": "#1C4599", - "hue_tolerance_pct": 0.07, - "value_cutoff_pct": 0.15 - } - }, - { - "name": "green_triangle", - "type": "vision", - "model": "color_detector", - "attributes": { - "segment_size_px": 200, - "detect_color": "#62963F", - "hue_tolerance_pct": 0.05, - "value_cutoff_pct": 0.20 - } - }, - ... // other services -] -``` - -{{% /tab %}} -{{% tab name="Old Way" %}} - -```json -"services": [ - { - "name": "vision", - "type": "vision", - "attributes": { - "register_models": [ - { - "parameters": { - "segment_size_px": 100, - "detect_color": "#1C4599", - "hue_tolerance_pct": 0.07, - "value_cutoff_pct": 0.15 - }, - "name": "blue_square", - "type": "color_detector" - }, - { - "parameters": { - "segment_size_px": 200, - "detect_color": "#62963F", - "hue_tolerance_pct": 0.05, - "value_cutoff_pct": 0.20 - }, - "name": "green_triangle", - "type": "color_detector" - } - ] - } - }, - ... // other services -] -``` - -{{% /tab %}} -{{< /tabs >}} - -#### TFLite detector configurations - -You can replace existing TFLite detectors by [configuring new ones in the UI](/services/vision/mlmodel/) or you can update the [JSON configuration of your machines](/configure/#the-configure-tab): - -{{< tabs >}} -{{% tab name="New Way" %}} - -```json -"services": [ - { - "name": "person_detector", - "type": "mlmodel", - "model": "tflite_cpu", - "attributes": { - "model_path": "/path/to/file.tflite", - "label_path": "/path/to/labels.tflite", - "num_threads": 1 - } - }, - { - "name": "person_detector", - "type": "vision", - "model": "mlmodel", - "attributes": { - "mlmodel_name": "person_detector" - } - }, - ... // other services -] -``` - -{{% /tab %}} -{{% tab name="Old Way" %}} - -```json -"services": [ - { - "name": "vision", - "type": "vision", - "attributes": { - "register_models": [ - { - "parameters": { - "model_path": "/path/to/file.tflite", - "label_path": "/path/to/labels.tflite", - "num_threads": 1 - }, - "name": "person_detector", - "type": "tflite_detector" - } - ] - } - }, - ... // other services -] -``` - -{{% /tab %}} -{{< /tabs >}} - -#### TFLite Classifier configurations - -You can replace existing TFLite classifiers by [configuring new ones in the UI](/services/vision/mlmodel/) or you can update the [JSON configuration of your machines](/configure/#the-configure-tab): - -{{< tabs >}} -{{% tab name="New Way" %}} - -```json -"services": [ - { - "name": "fruit_classifier", - "type": "mlmodel", - "model": "tflite_cpu", - "attributes": { - "model_path": "/path/to/classifier_file.tflite", - "label_path": "/path/to/classifier_labels.txt", - "num_threads": 1 - } - }, - { - "name": "fruit_classifier", - "type": "vision", - "model": "mlmodel", - "attributes": { - "mlmodel_name": "fruit_classifier" - } - }, - ... // other services -] -``` - -{{% /tab %}} -{{% tab name="Old Way" %}} - -```json -"services": [ - { - "name": "vision", - "type": "vision", - "attributes": { - "register_models": [ - { - "parameters": { - "model_path": "/path/to/classifier_file.tflite", - "label_path": "/path/to/classifier_labels.txt", - "num_threads": 1 - }, - "name": "fruit_classifier", - "type": "tflite_classifier" - } - ] - } - }, - ... // other services -] -``` - -{{% /tab %}} -{{< /tabs >}} - -#### Radius Clustering 3D segmenter configurations - -You can replace existing Radius Clustering 3D segmenters by [configuring new ones in the UI](/services/vision/obstacles_pointcloud/) or you can update the [JSON configuration of your machines](/configure/#the-configure-tab): - -{{< tabs >}} -{{% tab name="New Way" %}} - -```json -"services": [ - { - "name": "rc_segmenter", - "type": "vision", - "model": "obstacles_pointcloud" - "attributes": { - "min_points_in_plane": 1000, - "min_points_in_segment": 50, - "clustering_radius_mm": 3.2, - "mean_k_filtering": 10 - } - }, - ... // other services -] -``` - -{{% /tab %}} -{{% tab name="Old Way" %}} - -```json -"services": [ - { - "name": "vision", - "type": "vision", - "attributes": { - "register_models": [ - { - "parameters": { - "min_points_in_plane": 1000, - "min_points_in_segment": 50, - "clustering_radius_mm": 3.2, - "mean_k_filtering": 10 - }, - "name": "rc_segmenter", - "type": "radius_clustering_segmenter" - } - ] - } - }, - ... // other services -] -``` - -{{% /tab %}} -{{< /tabs >}} - -#### Detector to 3D segmenter configurations - -You can replace existing Radius Clustering 3D segmenters by [configuring new ones in the UI](/services/vision/detector_3d_segmenter/) or you can update the [JSON configuration of your machines](/configure/#the-configure-tab): - -{{< tabs >}} -{{% tab name="New Way" %}} - -```json -"services": [ - { - "name": "my_segmenter", - "type": "vision", - "model": "detector_3d_segmenter" - "attributes": { - "detector_name": "my_detector", - "confidence_threshold_pct": 0.5, - "mean_k": 50, - "sigma": 2.0 - } - }, - ... // other services -] -``` - -{{% /tab %}} -{{% tab name="Old Way" %}} - -```json -"services": [ - { - "name": "vision", - "type": "vision", - "attributes": { - "register_models": [ - { - "parameters": { - "detector_name": "my_detector", - "confidence_threshold_pct": 0.5, - "mean_k": 50, - "sigma": 2.0 - }, - "name": "my_segmenter", - "type": "detector_segmenter" - } - ] - } - }, - ... // other services -] -``` - -{{% /tab %}} -{{< /tabs >}} -{{% /expand%}} - -#### Add and remove models using the machine config - -You must add and remove models using the [machine config](/configure/). -You will no longer be able to add or remove models using the SDKs. - -#### Add machine learning vision models to a vision service - -The way to add machine learning vision models is changing. -You will need to first register the machine learning model file with the [ML model service](/services/ml/) and then add that registered model to a vision service. - -{{% /changelog %}} - -{{% changelog date="2023-03-31" color="added" title="Machine learning for image classification models" %}} - -You can now [train](/how-tos/train-deploy-ml/) and [deploy](/services/ml/) image classification models with the [data management service](/services/data/) and use your machine's image data directly within Viam. -Additionally, you can upload and use existing [machine learning models](/registry/ml-models/) with your machines. -For more information on using data synced to the cloud to train machine learning models, read [Train a model](/how-tos/train-deploy-ml/). - -{{% /changelog %}} - -{{% changelog date="2023-03-31" color="added" title="Motion planning with new `constraint` parameter" %}} - -A new parameter, [`constraint`](/services/motion/constraints/), has been added to the [Motion service API](/appendix/apis/services/motion/#api), allowing you to define restrictions on the machine's movement. -The constraint system also provides flexibility to specify that obstacles should only impact specific frames of a machine. - -{{% /changelog %}} - -{{% changelog date="2023-03-31" color="added" title="Fragments in machine configuration" %}} - -You can now access {{< glossary_tooltip term_id="fragment" text="fragments" >}} in your machine configuration. -The configurations you added will now show up automatically in the **Builder** view on your machine's **CONFIGURE** tab. -This makes it easier to monitor what fragments you've added to your machine and how they're configured. - -For more information, see [Fragments](/configure/#fragments). - -{{% /changelog %}} - -{{% changelog date="2023-03-31" color="improved" title="Sticky GPS keys" %}} - -GPS keys you enter are now saved in your local storage. -This ensures that when you reload the page, your GPS keys remain accessible. - -{{% /changelog %}} - -{{% changelog date="2023-03-31" color="improved" title="More reliable camera streams" %}} - -The camera component's streams are smoother and more reliable with recent improvements. - -Additionally, camera streams automatically restart if you momentarily lose internet connection. - -{{% /changelog %}} - -{{% changelog date="2023-03-31" color="improved" title="UI updates to Logs and History" %}} - -The latest UI updates enable you to: - -- Load a previous configuration for reverting changes made in the past -- Search logs by filtering keywords or log levels such as _info_ or _error_ messages -- Change your timestamp format to **ISO** or **Local** depending on your preference. - -{{% /changelog %}} - -{{% changelog date="2023-02-28" color="added" title="Rover reuse in Try Viam" %}} - -You now have the option to reuse a machine config from a previous Try Viam session. - -{{% /changelog %}} - -{{% changelog date="2023-02-28" color="added" title="Dynamic code samples" %}} - -The Viam app **Code sample** tab now dynamically updates as you add resources to your machine's config. -The code samples instantiate each resource and include examples of how to call a `Get` method on it. - -{{% /changelog %}} - -{{% changelog date="2023-02-28" color="added" title="TypeScript SDK" %}} - -Find more information in the [TypeScript SDK docs](https://ts.viam.dev/). - -{{% /changelog %}} - -{{% changelog date="2023-02-28" color="added" title="Frame system visualizer" %}} - -When adding [frames](/services/frame-system/) to your machine's config in the Viam app, you can now use the **Frame System** subtab of the **CONFIGURE** tab to more easily visualize the relative positions of frames. - -{{% /changelog %}} - -{{% changelog date="2023-02-28" color="added" title="Support for microcontrollers" %}} - -`viam-micro-server` is a lightweight version of `viam-server` that can run on an ESP32. -Find more information in the [`viam-micro-server` installation docs](/installation/viam-micro-server-setup/#install-viam-micro-server). - -{{% /changelog %}} - -{{% changelog date="2023-01-31" color="added" title="Remote control power input" %}} - -On your machine's **CONTROL** tab on the [Viam app](https://app.viam.com/), you can now set the power of a [base](/components/base/). -The base control UI previously always sent 100% power to the base's motors. - -{{% /changelog %}} - -{{% changelog date="2023-01-31" color="added" title="New encoder model: AMS AS5048" %}} - -The [AMS AS5048](https://github.com/viam-modules/ams) is now supported. - -{{% /changelog %}} - -{{% changelog date="2023-01-31" color="added" title="GetLinearAcceleration method" %}} - -The movement sensor API now includes a [GetLinearAcceleration](/appendix/apis/components/movement-sensor/#getlinearacceleration) method. - -{{% /changelog %}} - -{{% changelog date="2023-01-31" color="added" title="Support for capsule geometry" %}} - -The [motion service](/services/motion/) now supports capsule geometries. - -The UR5 arm model has been improved using this new geometry type. - -{{% /changelog %}} - -{{% changelog date="2022-12-28" color="added" title="Modular resources" %}} - -You can now implement your own custom {{< glossary_tooltip term_id="resource" text="resources" >}} as [_modular resources_](/registry/). - -{{% alert title="Important: Breaking Change" color="note" %}} - -All users need to update to the latest version of the RDK (V3.0.0) to access machines using the Viam app. - -{{% /alert %}} - -{{% /changelog %}} - -{{% changelog date="2022-12-28" color="added" title="URDF kinematic file support" %}} - -You can now supply kinematic information using URDF files when implementing your own arm models. - -{{% /changelog %}} - -{{% changelog date="2022-12-28" color="added" title="New movement sensor models" %}} - -There are two new movement sensor {{< glossary_tooltip term_id="model" text="models" >}}: - -- [ADXL345](https://github.com/viam-modules/analog-devices): A 3-axis accelerometer -- [MPU-6050](https://github.com/viam-modules/tdk-invensense): A 6-axis accelerometer and gyroscope - -{{% /changelog %}} - -{{% changelog date="2022-12-28" color="improved" title="Camera performance and reliability" %}} - -- Improved server-side logic to choose a mime type based on the camera image type, unless a specified mime type is supplied in the request. - **The default mime type for color cameras is now JPEG**, which improves the streaming rate across every SDK. -- Added discoverability when a camera reconnects without changing video paths. - This now triggers the camera discovery process, where previously users would need to manually restart the RDK to reconnect to the camera. - -{{% /changelog %}} - -{{% changelog date="2022-12-28" color="improved" title="Motion planning with remote components" %}} - -The [motion service](/services/motion/) is now agnostic to the networking topology of a machine. - -- Kinematic information is now transferred over the robot API. - This means that the motion service is able to get kinematic information for every component on the machine, regardless of whether it is on a main or remote viam-server. -- Arms are now an input to the motion service. - This means that the motion service can plan for a machine that has an arm component regardless of whether the arm is connected to a main or {{< glossary_tooltip term_id="remote-part" text="remote-part" >}} instance of `viam-server`. - -{{% /changelog %}} - -{{% changelog date="2022-12-28" color="improved" title="Motion planning path smoothing" %}} - -- RRT\* paths now undergo rudimentary smoothing, resulting in improvements to path quality with negligible change to planning performance. -- Plan manager now performs direct interpolation for any solution within some factor of the best score, instead of only in the case where the best inverse kinematics solution could be interpolated. - -{{% /changelog %}} - -{{% changelog date="2022-12-28" color="improved" title="Data synchronization reliability" %}} - -Previously, data synchronization used bidirectional streaming. -Now is uses a simpler unary approach that is more performant on batched unary calls, is easier to load balance, and maintains ordered captures. - -{{% /changelog %}} - -{{% changelog date="2022-11-28" color="changed" title="Camera configuration" %}} - -**Changed** the configuration schemes for the following camera models: - -- Webcam -- FFmpeg -- Transform -- Join pointclouds - -For information on configuring any camera model, see [Camera Component](/components/camera/). - -{{% /changelog %}} - -{{% changelog date="2022-11-15" color="added" title="New servo model" %}} - -A new [servo model called `gpio`](/components/servo/gpio/) supports servos connected to non-Raspberry Pi boards. - -{{% /changelog %}} - -{{% changelog date="2022-11-15" color="added" title="RTT indicator in the app" %}} - -A badge in the Viam app now displays RTT (round trip time) of a request from your client to the machine. -Find this indicator of the time to complete one request/response cycle on your machine's **CONTROL** tab, in the **Operations & Sessions** card. - -{{% /changelog %}} - -{{% changelog date="2022-11-15" color="added" title="Python 3.8 support" %}} - -The Python SDK now supports Python 3.8, in addition to 3.9 and 3.10. - -{{% /changelog %}} - -{{% changelog date="2022-11-15" color="added" title="New parameter: `extra`" %}} - -A new API method parameter, `extra`, allows you to extend {{< glossary_tooltip term_id="modular-resource" text="modular resource" >}} functionality by implementing the new field according to whatever logic you choose. -`extra` has been added to the following APIs: arm, data management, gripper, input controller, motion, movement sensor, navigation, pose tracker, sensor, SLAM, vision. - -{{% alert title="IMPORTANT: Breaking change" color="note" %}} - -Users of the Go SDK _must_ update code to specify `extra` in the arguments that pass into each request. - -`extra` is an optional parameter in the Python SDK. - -{{% /alert %}} - -{{% /changelog %}} - -{{% changelog date="2022-11-15" color="added" title="Service dependencies" %}} - -`viam-server` now initializes and configures resources in the correct order. -For example, if the SLAM service depends on a LiDAR, it will always initialize the LiDAR before the SLAM service. - -{{% alert title="IMPORTANT: Breaking change" color="note" %}} - -If you are using the SLAM service, you now need to specify sensors used by the SLAM service in the `depends_on` field of the SLAM configuration. -Other service configurations are not affected. - -{{% /alert %}} - -{{% /changelog %}} - -{{% changelog date="2022-11-15" color="removed" title="Width and height fields from camera API" %}} - -Removed `width` and `height` from the response of the [`GetImage`](/appendix/apis/components/camera/#getimage) method in the camera API. -This does not impact any existing camera models. -If you write a custom camera model, you no longer need to implement the `width` and `height` fields. - -{{% /changelog %}} diff --git a/docs/appendix/contributing.md b/docs/appendix/contributing.md deleted file mode 100644 index 669d5d41299..00000000000 --- a/docs/appendix/contributing.md +++ /dev/null @@ -1,893 +0,0 @@ ---- -title: "Contributing to the Docs" -linkTitle: "Contributing to the docs" -weight: 99 -type: "docs" -description: "Learn about our style guide and how to work with hugo to contribute to these docs." -toc_hide: true ---- - -Thank you for wanting to help us make the docs better. -Every contribution is appreciated. - -{{< alert title="Note" color="note" >}} -Before you start, please review this document and our [Code of Conduct](https://www.viam.com/community-guidelines). -{{< /alert >}} - -## Goals - -The Viam documentation aims to: - -- Educate users (explain concepts, provide an overview of what is possible) -- Help users accomplish tasks (performing an action, building a thing) - -We do that by providing concise and well-structured documentation to users. -When users stumble, we provide avenues for feedback, so we can take action and prevent other users from running into similar issues. - -## Voice - -We aim to be friendly but not colloquial, direct, and concise. - -Here are a few additional pointers: - -| Subject | Judgment | -| -------------------- | ------------- | -| Emoji ✨ | No | -| Exclamation marks | Use sparingly | -| Rhetorical questions | No | - -## Audience - -We write for a technical audience that spans from entry-level to expert. -However, common tools and concepts such as version control, moving files with ssh, JSON are beyond the scope of our docs. -To make the content as accessible as possible we will, where possible, include actions to be taken and text that guides the user as to what they are achieving when performing these actions. - -For example, when copying a file to another machine with ssh, we would describe the action with words like "Use ssh to move the file onto the other machine" alongside the command to move the file. -Explaining ssh goes beyond the scope of our docs. -Where needed, we will link to supporting documentation but not provide supporting documentation ourselves where it would duplicate existing external documentation. -Use your judgment to determine when we need to explain more and when we need to link to supporting content. -When in doubt, ask during review. - -## Project structure - -All documentation is in the [docs folder](https://github.com/viamrobotics/docs/tree/main/docs). -For information about Hugo and how to develop locally, see the [README](https://github.com/viamrobotics/docs/blob/main/README.md). - -## Content types - -When creating a new piece of content, decide which one of the four content types the content should be. -Note this in a comment in the front matter of the file. - -The docs use the [Diátaxis Framework](https://diataxis.fr/) as the basis of the content structure with the following four content types: - -- **Explanation (conceptual)**: An understanding-oriented piece of content. - This content provides background knowledge on a topic and tends to be referenced in how-to guides and tutorials. - For example the [`viam-server` page](/architecture/viam-server/) or the [Registry page](/registry/). - It’s useful to have a real or imagined "Why?" question to serve as a prompt. - - {{< expand "Click to view template" >}} - - ```md - # Concept - - Introductory paragraph. - Possibly containing further subsections or links to relevant conceptual information. - - ## Subconcept - - Paragraphs containing explanation. Add imagery as needed. - - - Provide context and address potential points of confusion. - Add real or hypothetical examples. - - Possibly more Subconcept sections. - - ### Do x with subconcept (optional) - - Information on potential ways to apply the concept (possibly linking to how-tos or containing how-tos). - - ## Next steps - - Links to related content. - ``` - - {{< /expand >}} - -- **How-to Guide (procedural)**: A task-oriented piece of content that directs a reader to perform actions step by step to complete a task, like instructions to sauté onions. - Generally starts with a description of the task and things to consider, and then provides a set of numbered steps to follow. - For example, the [Installation page](/installation/viam-server-setup/) or the [Find module page](/registry/modular-resources/). - - {{< expand "Click to view template" >}} - - ```md - # Do This Task - - Description of task and considerations. Possibly containing further subsections. - - ## Do x - - 1. Ordered list of actions to perform. Written in imperative form. Add imagery as needed. - - (possibly more Do X sections) - - ## Next steps - - Links to related content. - ``` - - {{< /expand >}} - -- **Tutorial**: A learning-oriented piece of content that functions as a lesson for the reader. - A tutorial helps readers to learn and apply skills by doing something meaningful and attainable, like a recipe to cook a full meal. - - {{< expand "Click to view template" >}} - - ```md - # Do X with Y - - Outline the why. - Tell the story of the machine. - Explain the machine's use and origin. - - ## Requirements - - What does the reader need to already know. - What will you be using (hardware/software). - - ## Build X - - Build steps. - - ## Configure your X - - Configuration steps. - - ## Program your X - - Code and directions. - - ## Next steps - - Link to other tutorials with cards or text. - - {{}} - {{%/* card link="/tutorials/get-started/blink-an-led" */%}} - {{}} - ``` - - For the full template see [template.md](https://github.com/viamrobotics/docs/blob/main/docs/tutorials/template.md). - - {{< /expand >}} - -- **Reference**: A concise, information-oriented piece of content that generally starts with an overview/introduction and then a list of some kind (configuration options, API methods, etc.). - Examples include the [API pages](/appendix/apis/) as well as [component and service pages](/components/arm/). - - Example template: [Component template](https://github.com/viamrobotics/docs/blob/main/docs/components/component/_index.md). - - {{< expand "Click to view template" >}} - - ```md - # Product, Feature or API Name - - Description or introduction. - Possibly containing further subsections. - - ## List or table of items (heading optional as needed) - - - Unordered list of options - - (possibly more information for each option) - - ## Next steps - - Links to related content. - ``` - - {{< /expand >}} - -## Style guide - -All docs are written in [Hugo Markdown](https://www.markdownguide.org/tools/hugo/). -Most Markdown formatting is supported. -For a brief introduction to Markdown, check out this [Markdown Cheatsheet](https://gist.github.com/npentrel/e1dd14816f7c7724edf70ab2a2ed2952). -Some additional formatting options are supported with [Hugo Shortcodes](https://gohugo.io/content-management/shortcodes/). - -We follow the [Rackspace Style Guide](https://web.archive.org/web/20200829151826/https://developer.rackspace.com/docs/style-guide/) with many rules encoded in Vale rules. - -Additional we enforce the following substitutions: - - - -| Do not say | Instead say | -| ---------- | ----------- | -| web app, cloud app | Viam app or Viam platform | -| viam app, Viam App | Viam app | -| Viam-server, Viam server, Viam-Server | viam-server | -| Config Tab, Config tab, Configure Tab | CONFIGURE tab | -| Vision service, Vision Service | vision service | -| Motion service, Motion Service | motion service | -| slam service, Slam service, SLAM Service | SLAM service | -| Data Management Service, Data Management service | data management service | -| in the website | on the website | -| on the app | in the app | -| user of an org | member of an org | -| main part and child part, main part and non-main part | main part and sub-part | -| subpart | sub-part | -| drop down | dropdown | -| drop-down | dropdown | -| RPLIDAR, Rplidar | RPlidar | -| compute parts | computer | -| microprocessor | Raspberry Pi or Jetson or another specific term | - - - -### Vale linting - -{{< alert title="Tip" color="tip" >}} -We recommend you work in Visual Studio Code and install the [Vale extension](https://marketplace.visualstudio.com/items?itemName=errata-ai.vale-server) to use the vale linter. -{{< /alert >}} - -When you open a PR, your changes will be checked against a few style rules. -To run this check locally, follow the instructions in the [Vale Readme](https://github.com/viamrobotics/docs/blob/main/.github/vale/README.md). - -### `markdownlint` - -We recommend you work in Visual Studio Code and install the [markdownlint extension](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint). - -### UI elements - -Use **bold** text for UI elements, such as tabs and buttons. - -### Example values - -Use examples that resemble real data. For emails this could be `amanda@viam.com`. - -When using placeholders in code examples, follow the [Google developer documentation style guide's rules for formatting placeholders](https://developers.google.com/style/placeholders). - -### Images and screenshots - -Use screenshots in introductory materials and where the surrounding text is not enough to direct the reader. Be aware that screenshots tend to get outdated quickly and come with a maintenance burden. - -Rules for images: - -- **Place images in the `assets` folder.** The folder uses the same content structure as the docs. Your images should be in the folder the page that uses it is in. However, there is no need to duplicate an image into multiple places if you use it in multiple pages. -- All images require alt text. -- All images **should** be smaller than 1MB. Hugo throws a warning during local builds (such as `make serve-prod`) if an image exceeds this size. Use an image compressor like [TinyPNG](https://tinypng.com/). This is to reduce the overall page and repo size. - -#### Remove EXIF data automatically - -{{< alert title="Important" color="note" >}} - -To ensure that you do not accidentally add `EXIF` data on images, please install [exiftool](https://exiftool.org/install.html) and add the following lines to the `.git/hooks/pre-commit` file in your local repository. - -```sh {class="command-line" data-prompt="$"} -if [ "git diff --name-only | grep -EI '.*(png|jpg|jpeg)$' | wc -l" ]; -then -list= $(git diff --diff-filter=d --name-only | grep -EI ".*(png|jpg|jpeg)$") -for item in $list -do -exiftool -all= $item -done -fi -``` - -If you don't already have a `.git/hooks/pre-commit` file in your `docs` git repo directory, you can copy the existing `pre-commit.sample` file in that directory as `pre-commit` to use the sample template, or create a new `pre-commit` file in that directory with the above content. -If you create a new file, you must also make it executable with: `chmod 755 /path/to/my/.git/hooks/pre-commit`. - -With this configuration in place, each commit you make will remove EXIF data from any image files (with extension `.png`, `.jpg`, or `.jpeg`) that are part of your commit. -{{< /alert >}} - -#### Image markup - -If the image is supposed to take up the full width of the page use the regular markdown syntax: `![alt text](path)`. - -```md -![Raspberry Pi](/installation/thumbnails/raspberry-pi-4-b-2gb.png) -``` - -If the image is smaller use the `imgproc` shortcode with an appropriate resize value. - -```md - - -{ {} } - -{ {} } - -{ {} } -``` - -![Raspberry Pi](/installation/thumbnails/raspberry-pi-4-b-2gb.png) - -{{}} - -{{}} - -The `imgproc` shortcode will: - -- convert the image into the `webp` format (which is more efficient) and resize the image -- resize the image in the current format and set that image as a backup in case `webp` is not supported. This does reduce file size when the website is being served. However, the source file should still be smaller than 1MB to minimize overall page and repo size. For more information on the resize options see [Image Processing](https://gohugo.io/content-management/image-processing/). - -Only specify `declaredimensions` if the image is **not** responsive (if it doesn't resize). The only images that you'd want to use declaredimensions on are the ones that take up the same space on mobile as on desktop. - -An example of this are the small board icons on the front page which should never be a different size than they are. -The pictures in cards, however, need to resize because they change size based on the available screen space. - -Screenshot should most often be added with normal markdown syntax. Then they'll take up the max size they can on a big screen but be smaller on mobile. If you want to resize a large image, use the largest size the image can take up as the image to `resize` the image to. - -{{< alert title="Note" color="note" >}} -You cannot directly use the `` html tag for images in the assets folder because the images, once built, are renamed. -If you really need to use html directly, place the image in the `static` folder. -{{< /alert >}} - -### GIFs and videos - -We encourage the use of GIFs and Videos. -Our docs have two kinds of videos: - -- Regular videos with video controls and audio -- GIF-like videos that do not have video controls or audio and function like GIFs - -#### Regular videos - -For regular videos that should use the video shortcode as follows: - -```md - - -{ {
{{- else -}} - {{- errorf "Card has a bad link: %s" $link -}} + {{- warnf "Card has a bad link: %s" $link -}} {{- end -}} {{- end -}} diff --git a/layouts/partials/glossary-terms.html b/layouts/partials/glossary-terms.html index 47030ff7bd4..c9fbf18482d 100644 --- a/layouts/partials/glossary-terms.html +++ b/layouts/partials/glossary-terms.html @@ -1,7 +1,7 @@ -{{ $glossaryItems := site.GetPage "page" "appendix/glossary" }} +{{ $glossaryItems := site.GetPage "page" "dev/reference/glossary" }} {{- if $glossaryItems -}} {{ $pages := $glossaryItems.Resources.ByType "page" }} {{- $.Scratch.Set "glossary_items" $pages -}} {{- else -}} -{{- errorf "No glossary items. Please create items in appendix/glossary" -}} +{{- errorf "No glossary items. Please create items in dev/reference/glossary" -}} {{- end -}} \ No newline at end of file diff --git a/layouts/partials/navbar.html b/layouts/partials/navbar.html index 493f43b22f8..04c48108386 100644 --- a/layouts/partials/navbar.html +++ b/layouts/partials/navbar.html @@ -4,59 +4,71 @@ -}} diff --git a/layouts/partials/sidebar-tree.html b/layouts/partials/sidebar-tree.html index 039786ccd51..586669223b6 100644 --- a/layouts/partials/sidebar-tree.html +++ b/layouts/partials/sidebar-tree.html @@ -40,7 +40,7 @@ {{ $ulNr := .ulNr -}} {{ $ulShow := .ulShow -}} {{ $active := and (not $shouldDelayActive) (eq $s $p) -}} -{{ $activePath := and (not $shouldDelayActive) ($p.IsDescendant $s) -}} +{{ $activePath := and (not $shouldDelayActive) (or ($p.IsDescendant $s) (eq $p $s)) -}} {{ $show := cond (or (lt $ulNr $ulShow) $activePath (and (not $shouldDelayActive) (eq $s.Parent $p.Parent)) (and (not $shouldDelayActive) (eq $s.Parent $p)) (not $p.Site.Params.ui.sidebar_menu_compact) (and (not $shouldDelayActive) ($p.IsDescendant $s.Parent))) true false -}} {{ $mid := printf "m-%s" ($s.RelPermalink | anchorize) -}} {{ $pages_tmp := where (union $s.Pages $s.Sections).ByWeight ".Params.toc_hide" "!=" true -}} @@ -50,7 +50,9 @@ {{ $manualLink := cond (isset $s.Params "manuallink") $s.Params.manualLink ( cond (isset $s.Params "manuallinkrelref") (relref $s $s.Params.manualLinkRelref) $s.RelPermalink) -}} {{ $manualLinkTitle := cond (isset $s.Params "manuallinktitle") $s.Params.manualLinkTitle $s.Title -}} {{ $empty_node := $s.Params.empty_node -}} -
  • +{{ $openOnDesk := $s.Params.open_on_desktop }} +{{ $headerOnly := $s.Params.header_only }} +
  • {{ if (and $p.Site.Params.ui.sidebar_menu_foldable (ge $ulNr 1)) -}}