DOCS-3699, DOCS-2567: Add module lifecycle and dependencies guidance #4156

JessamyT · 2025-03-27T00:46:45Z

Discovery service will be further fleshed out separately

Staging:
https://deploy-preview-4156--viam-docs.netlify.app/operate/get-started/other-hardware/#how-and-where-do-modules-run and https://deploy-preview-4156--viam-docs.netlify.app/operate/get-started/other-hardware/dependencies/

netlify · 2025-03-27T00:47:03Z

✅ Deploy Preview for viam-docs ready!

Name	Link
🔨 Latest commit	`c114a25`
🔍 Latest deploy log	https://app.netlify.com/sites/viam-docs/deploys/67ed7b5a4fb394000853347e
😎 Deploy Preview	https://deploy-preview-4156--viam-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
Lighthouse	1 paths audited Performance: 41 (🟢 up 15 from production) Accessibility: 100 (no change from production) Best Practices: 100 (no change from production) SEO: 100 (🟢 up 8 from production) PWA: 60 (🔴 down 10 from production) View the detailed breakdown and full score reports

To edit notification comments on pull requests, go to your Netlify site configuration.

michaellee1019 · 2025-03-27T19:31:42Z

docs/operate/get-started/other-hardware/dependencies.md

@@ -191,7 +191,7 @@ If you need to maintain the state of your resource, see [(Optional) Create and e
 {{< tabs >}}
 {{% tab name="Python" %}}

-If you prefer to use explicit dependencies (for example, for an optional dependency), the steps are the same as for implicit dependencies above, except that you do not need to return the dependency from the `validate_config` method and can instead return an empty list:
+If you prefer to use explicit dependencies (for example, for an optional dependency), the steps are the same as for implicit dependencies, except that you do not need to return the dependency from the `validate_config` method and can instead return an empty list:


I think that saying "for example, for an optional dependency" is wrong here. A resource will still wait for all resources declared in depends_on to be available before starting.

We have two mechanisms for declaring dependencies which are essentially the same result. Implicit is more common than explicit

What I mean by "optional" here is that if the user doesn't configure a "camera_name" at all, either in depends_on or in attributes, that the modular resource should still work. But I'm realizing the example I have here doesn't indicate that--I should make this validate_config explicit dependency example show "camera_name" as an optional attribute, and keep it as a required attribute for the implicit dependency example.

Is it true that people should use implicit dependencies for required things and explicit dependencies for optional things?

I guess, is it currently possible for people to have an optional implicit dependency, or not until the upcoming work happens?

No way to have an optional explicit dependency. Yeah you could make an implicit dependency optional. Its a bit annoying right now:

See in validate that its not defined and don't return it as a dependency.

In your implementation you check to make sure the dependency is not null and gracefully skip using it.

To illuminate other reviewers: Based on offline sync, we were using "optional" in different ways--If a user does put something in depends_on, the resource won't currently start if the dependency doesn't start. What I was meaning with "optional" is it's optional for the user to even configure it at all. But sounds like you can do that with either implicit or explicit deps--it's all about how you implement validate.

Based on offline convo I will remove explicit dependencies since they just confuse users and aren't actually necessary except in cases of backwards compatibility.

JessamyT · 2025-03-27T20:19:06Z

docs/operate/get-started/other-hardware/dependencies.md

+{{< /tabs >}}
+
+{{% hiddencontent %}}
+There is not currently an SDK method to access configuration attributes of dependencies in Python or Go, but in Python it is possible to use `get_robot_part` to return information including the whole configuration of a machine part, and then access the configuration attributes of the dependency from there.


Maybe this isn't right--looking into this more

JessamyT · 2025-03-28T01:56:46Z

@michaellee1019 I changed it to optional vs required but LMK if you think that is still confusing or overkill and it'd be better to just have one heading with "use dependencies" in general, with the required deps examples, and omit the optional examples.

docs/operate/get-started/other-hardware/_index.md

cheukt

did a quick pass, I'll be out next week so no need for my approval - if we want an opinion from netcode we can add @benjirewis

docs/operate/get-started/other-hardware/_index.md

cheukt · 2025-03-28T15:22:36Z

docs/operate/get-started/other-hardware/dependencies.md

+{{< /tabs >}}
+
+{{% hiddencontent %}}
+There is not currently an SDK method to directly access configuration attributes of dependencies in Python or Go, but in Python it is possible to use `get_robot_part` to return information including the whole configuration of a machine part, and then access the configuration attributes of the dependency from there.


what does this mean? I think we would want to discourage users from looking at configs for other resources

We got a chatbot question about this specifically (from Sean Yu) and the bot answer was incorrect so was hoping to fix it. This hidden content short code means it’s not visible on the page, only to the chatbot if someone specifically asks. But if we don’t want people to do this at all should I just change this to say “you can’t, period”?

ok, I guess in that case this is fine - we should definitely discourage it tho

benjirewis

This is awesome! You guys do a great job of adding stuff around this somewhat opaque logic. Some comments and I can help further while Cheuk is on PTO.

docs/operate/get-started/other-hardware/_index.md

benjirewis · 2025-03-28T18:58:57Z

docs/operate/get-started/other-hardware/dependencies.md

+     if cfg.CameraName == "" {
+       return nil, resource.NewConfigValidationFieldRequiredError(path, "camera_name")
+     }
+     if reflect.TypeOf(cfg.CameraName).Kind() != reflect.String {


I don't think you need this reflection check. cfg.CameraName will definitely be a string at this point.

Does it get checked by viam-server automatically because CameraName string json:"camera_name" specifies type?

Basically yep! It's not technically viam-server that does the conversion from proto to a golang string, but the Golang module library code does it and will error if the thing specified in JSON is not actually a string/cfg.CameraName will just "".

Ah okay ty!! Wait it'll error or it'll assign it an empty string or both?

Sorry for ambiguity! There will be an error during validation for the resource if camera_name is not a string in the JSON.

docs/operate/get-started/other-hardware/dependencies.md

michaellee1019

Read through it and LGTM! A great improvement. I would double check on that comment thread with net code about the exact shutdown behavior. It might warrant a quick explanation about the overall timing, and then a more detailed section with the caveats about the shutdown timing based on the modules behavior. For example:

When `viam-server` shuts down, it attempts to stop all running modules. This can take up to x seconds depending on the response time required by a module to shut down.

And then a section that describes the shutdown and killing behavior.

JessamyT · 2025-03-31T17:27:52Z

Thanks!

Benji okayed the suggestion on that thread via slack so I went ahead and committed now

benjirewis

All LGTM!

docs/operate/get-started/other-hardware/_index.md

github-actions · 2025-04-04T16:58:07Z

🔎💬 Inkeep AI search and chat service is syncing content for source 'Viam Docs (https://docs.viam.com)'

viambot added the safe to build This pull request is marked safe to build from a trusted zone label Mar 27, 2025

JessamyT force-pushed the 3699modules branch from b0062e1 to 1a5e569 Compare March 27, 2025 00:47

JessamyT requested review from michaellee1019 and cheukt March 27, 2025 00:48

michaellee1019 reviewed Mar 27, 2025

View reviewed changes

JessamyT commented Mar 27, 2025

View reviewed changes

JessamyT added 9 commits March 27, 2025 18:54

DOCS-3699: Add module dependencies guidance

e495137

Add more content including Python examples and hidden content

167ded9

Add implicit Go and add explicit

60b6f1d

Fix viam-server, move lifecycle to expander, etc

af654bc

lint

41c21ec

Fix nits/linter

ff1f74c

Change explicit validate to make attr optional

5899106

lint

06fd06c

Deprecate explicit deps and change wording to optional or required

bb8a644

JessamyT force-pushed the 3699modules branch from 5b0f92e to bb8a644 Compare March 28, 2025 01:54

JessamyT requested a review from michaellee1019 March 28, 2025 01:54

JessamyT commented Mar 28, 2025

View reviewed changes

docs/operate/get-started/other-hardware/_index.md Outdated Show resolved Hide resolved

cheukt reviewed Mar 28, 2025

View reviewed changes

benjirewis reviewed Mar 28, 2025

View reviewed changes

JessamyT and others added 2 commits March 28, 2025 13:18

Apply suggestions from code review

7863bb2

Remove unnecessary go camera_name type check

ae38347

michaellee1019 approved these changes Mar 31, 2025

View reviewed changes

Apply suggestions from code review

f832da9

benjirewis approved these changes Mar 31, 2025

View reviewed changes

docs/operate/get-started/other-hardware/_index.md Show resolved Hide resolved

JessamyT requested a review from npentrel March 31, 2025 17:50

npentrel reviewed Apr 1, 2025

View reviewed changes

docs/operate/get-started/other-hardware/_index.md Outdated Show resolved Hide resolved

docs/operate/get-started/other-hardware/_index.md Outdated Show resolved Hide resolved

docs/operate/get-started/other-hardware/_index.md Outdated Show resolved Hide resolved

JessamyT commented Apr 1, 2025

View reviewed changes

docs/operate/get-started/other-hardware/_index.md Outdated Show resolved Hide resolved

JessamyT added 2 commits April 1, 2025 12:58

Update docs/operate/get-started/other-hardware/_index.md

32ca2d5

Apply suggestions from code review

c114a25

JessamyT requested a review from npentrel April 2, 2025 18:51

npentrel approved these changes Apr 4, 2025

View reviewed changes

JessamyT merged commit 09d2837 into viamrobotics:main Apr 4, 2025
12 checks passed

JessamyT deleted the 3699modules branch April 4, 2025 16:57

JessamyT changed the title ~~DOCS-3699, DOCS-2540: Add module lifecycle and dependencies guidance~~ DOCS-3699, DOCS-2567: Add module lifecycle and dependencies guidance Apr 4, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

DOCS-3699, DOCS-2567: Add module lifecycle and dependencies guidance #4156

DOCS-3699, DOCS-2567: Add module lifecycle and dependencies guidance #4156

JessamyT commented Mar 27, 2025 •

edited

Loading

netlify bot commented Mar 27, 2025 •

edited

Loading

michaellee1019 Mar 27, 2025

michaellee1019 Mar 27, 2025

JessamyT Mar 27, 2025

JessamyT Mar 27, 2025

michaellee1019 Mar 27, 2025

JessamyT Mar 27, 2025

JessamyT Mar 27, 2025

JessamyT commented Mar 28, 2025

cheukt left a comment

cheukt Mar 28, 2025

JessamyT Mar 28, 2025

cheukt Mar 28, 2025

benjirewis left a comment

benjirewis Mar 28, 2025

JessamyT Mar 28, 2025

benjirewis Mar 28, 2025

JessamyT Mar 28, 2025

benjirewis Apr 2, 2025

michaellee1019 left a comment

JessamyT commented Mar 31, 2025 •

edited

Loading

benjirewis left a comment

github-actions bot commented Apr 4, 2025

DOCS-3699, DOCS-2567: Add module lifecycle and dependencies guidance #4156

DOCS-3699, DOCS-2567: Add module lifecycle and dependencies guidance #4156

Conversation

JessamyT commented Mar 27, 2025 • edited Loading

netlify bot commented Mar 27, 2025 • edited Loading

✅ Deploy Preview for viam-docs ready!

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

JessamyT commented Mar 28, 2025

cheukt left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

benjirewis left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

michaellee1019 left a comment

Choose a reason for hiding this comment

JessamyT commented Mar 31, 2025 • edited Loading

benjirewis left a comment

Choose a reason for hiding this comment

github-actions bot commented Apr 4, 2025

JessamyT commented Mar 27, 2025 •

edited

Loading

netlify bot commented Mar 27, 2025 •

edited

Loading

JessamyT commented Mar 31, 2025 •

edited

Loading