OpenHTF Documentation

[jpl-harmattan]

Hi all,

I'm pretty new to OpenHTF, and I'm amazed at how well the project has lasted even though it started almost 10 years ago! It seems a lot of people are using the library and are happy using it.

However, one question still stands:

Why is there no proper documentation ?

I'm starting this discussion to gather feedback from users about OpenHTF and hopefully get an initial official documentation going for the project. I'm willing to spend some time writing things down, but I'm not that old on this project so I'm missing a lot of knowledge to dive into the details.

By the way, I'm glad to talk with anybody who's interested in this endeavor. Let's join forces and take advantage of the beauty of Open-Source Software!

PS: I'm sure we can close #44 before it's 10years old @glados-verma 😄

[charlottEv]

Hi @jpl-deepmine,

With the lack of documentation, we wrote an open-source one. You can find it here openhtf.com or on the open Github repo). Had you seen it before?

It took us quite a bit of effort to make a full documentation, so we'd love to get your feedback!

[charlottEv]

Hi @jpl-harmattan,

Thanks for your message. We’re glad the documentation helped you get started with OpenHTF.

I completely understand, and it's something we had already noticed. We want the documentation to be as clear and accessible as possible. In the coming weeks, we plan to remove the TofuPilot examples and keep the focus solely on OpenHTF to make it more "neutral," as you mentioned.

I also saw your message to Glados-verma—thanks for your feedback on the IMU calibration template. If you have specific suggestions, we’d love to hear what you need. Migrating your internal documentation into the public docs could also be a great way to make this knowledge more widely accessible. And I look forward to your list of questions so we can improve the documentation experience for everyone.

Thanks (and enjoy your time off! 😊)

[charlottEv]

Hi @jpl-harmattan,

The OpenHTF documentation has just been updated. We removed all TofuPilot examples to make the pages more neutral and showcase only OpenHTF code examples. We centralized and condensed all TofuPilot-related information into a single Analytics page.

I'd love to hear your feedback on these changes.

Looking forward to your comments and any questions you've already noted!

[jpl-harmattan]

Thanks for the heads up!

I had a look and it definitely looks clearer for readers. I just think you should have a little bit more explicit distinction between documentation related to openhtf and tofupilot. What I mean is that right now the navigation bar (on the left side of the page) puts on the same level Get Started, Develop and Resources even though currently the content in Manufacturing Test Analytics inside of Resources doesn't relate to Openhtf but to Tofupilot.
Another example of this is the fact that the image displayed at the top of each page (DUT for example) is from the TofuPilot UI I believe. That makes things confusing because users will probably expect the openhtf UI to look like the image which is not the case.

I think it would be best to have a separate page dedicated to how Tofupilot integrates with OpenHTF. The way I see things, the final goal is to have the openhtf.com documentation be mentioned on the openhtf repo, but I don't see how that would be possible if there are still links/direct references to TofuPilot in the current doc.

[jpl-harmattan]

Regarding my questions, here are a few that remain unanswered. They actually probably involve both the docs as well as knowledge about openhtf:

• Let's say you want to start up an actuator and read sensor data while the actuator is controlled. You then stop reading from the sensor once the actuator stops moving. Should you do one phase, several phases?

• If you are reading 2 sensor values in parallel (Ampmeter and temp sensor for example, each with their own plug), does openhtf have a way to synchronize the data, or does the user do it manually?

• Why use test.state.update(data) instead of test.attach(data) and then load that data in another phase with test.get_attachment(attachement_name) ?

• Why “lambda“ when defining a Serial Number in a test execution : test.execute(lambda: "PCB001")

• What is the test state ? What data does it store? What does it mean to update the test.state? Is the test state stored somewhere at the end of a test run?

• What is the difference between test.state.update() and test.state[“label“] = data

• Do you have plans to write documentation on Monitors?

PS: Also nice to see you changed the naming from UUT to DUT, thanks 😄 As a little side note however, I noticed that the name of the browser tab is still "Unit Under Test".

[charlottEv]

Thank you for your feedbacks! I’m currently preparing a v2 of the documentation UI, so I've taken note of your suggestions. Right now, we're focusing a lot on the content and will continue iterating quickly on that part. It's important that newcomers to OpenHTF, like you, have as much information as possible to get started.

And for your list of questions, here are the answers, and I'll note the ones that lack explanation to improve them in the documentation:

1. Actuator control with sensor readings:
   You can use a single phase for operations that require coordination. Since actuator control and sensor readings are related, it makes sense to group them in one phase. This allows you to control aspects like timing for both operations.
2. Parallel sensor reading:
   To my knowledge, OpenHTF doesn't have built-in mechanisms to synchronize data from multiple plugs. So you will need to manually synchronize readings.
3. test.state.update vs test.attach:

• test.state.update() modifies the test's running state (accessible between phases). Use state for temporary data needed by other phases.
• test.attach() creates a permanent attachment to the test record. Use attachments for items you want in the final test record.

4. Lambda for Serial Number:
   The lambda gives a function to provide the DUT. It's called when the test starts. This allows the serial number to be determined dynamically at runtime, for example, with a function to scan it.
5. Test state / update() / label:

• The test state is like a smart notebook that tracks important test information:
  • It stores data in a key-value format (like a dictionary).
  • It keeps track of measurements, phase results, and custom data.
  • Use test.state.update() to add or change multiple items at once.
  • Use test.state["label"] = data to store or update a single item.
• The test state allows you to share data between test phases, keep values available throughout the test, and save everything in the final test record.

PS: Good catch on the browser tab! Thanks 👍

[glados-verma]

I like your enthusiasm! This is definitely one of our long-due items in this repo.

It's great to see the TofuPilot team maintain tutorials and documentation for OpenHTF. It would be even better to have Wiki-style documentation here in the official repository ;) I opened up the Wiki for contributions; I am planning to add some initial docs after which it should be easier for contributors to, well, contribute.

@jpl-harmattan I'm curious, what documentation/examples did you refer to when you started using OpenHTF?

[jpl-harmattan]

Hi @glados-verma,

Thanks for your reply. For context, I'm starting a position as a test bench engineer and am in charge of setting up my company's testing jigs/fixtures for our production line (I'm starting from scratch). I've spent some time evaluating different frameworks, and in the end it seems like OpenHTF is a good option. I've reached out to several people who've been very satisfied with the library. The main downside people mention is the lack of documentation making "onboarding" pretty tough.

If we decide to use OpenHTF in the long run, I'll probably spend a lot of time working on some internal documentation for our future test engineers, and it doesn't make much sense to keep it to ourselves. My guess is a lot of other companies have created their own docs on OpenHTF so there probably mostly needs to be a collaborative effort to gather the pieces together.

And there's also a huge advantage in creating a proper documentation: More people will use the library and it'll be beneficial to the project in the long run. It's kind of a win-win situation the way I se it.

Regarding your question, I started off with openhtf.com (from Tofupilot) to write a few test cases. Then I looked at the hello_world.py and measurement.py scripts in the examples folder.

That was enough to get something going. I'm now trying to figure out if I should use a measurement in the case where I want to read a sensor (for say 5s) and then evaluate the average value of that sensor compared to a reference value. For now I can't seem to find a way of doing so with a Measurement and a Validator so I think I'll just skip that and use a dedicated Plug for the data processing.

I have to say that the IMU calibration template from Tofupilot is also a great resource. Hats off to their team!

Finally I tried running the frontend_example.py but with no luck for now (Blank Browser page) and no error message.

Anyways, overall I think this project has a lot of potential and I'm grateful that @glados-verma you're still on top of things! I'm looking forward to the future documentation we're going to get going!

[glados-verma]

Re: average measurement, I guess you want to be able to save all the samples but have a rule on the average value? There are a few ways you could do this:

1. Save the samples as a dimensioned measurement, and create a custom validator to compute their average value and do a pass fail. I think I prefer option 2...
2. Save samples as a dimensioned measurement, calculate average and save that as a regular "flat" measurement. Put a pass-fail rule on that
3. Use a Diagnosis - I've not used this part of OpenHTF so can't advise much.

Plugs are really only meant for things that you need to be able to definitively and deterministically tear down at the end of testing.

Let me get back to you on the rest of your message later.

[jpl-harmattan]

Okay thanks for your reply, I followed your suggestions (n°2) and just used a validator on the average. It works like a charm!

I didn't even look at what the Diagnosis does, but I'll read the inline documentation about it and maybe see if it's worth investigating further.

[jpl-harmattan]

FYI I'll be off for a few days until March 26th