bug: "Failed to initialize character device" message in Jupyter Notebook is confusing

[SyntaxColoring]

Overview

This message has a history of confusing users.

Our Support team has had a lot of users ask them how to "resolve the error." Since most users don't bother with the rail lights or other GPIO peripherals, this message is usually irrelevant, and Support's resolution is usually "just ignore it."

On the other hand, if the user will try to do something like turn on the rail lights, this message is important. But then, it's hard for most users to understand, anyway. Report #7179 was an example of this; it was surprising to the reporter that set_rail_lights() didn't work, even though this message theoretically warned them of that.

Steps to reproduce

Visit your OT-2's Jupyter Notebook and run:

import opentrons.execute
protocol = opentrons.execute.get_protocol_api('2.8')

Current behavior

• The message looks like an error, rather than an ignorable warning.
• It refers to the technical concepts gpio, smoothiekill, smoothie reset, robot server, and systemctl, which are probably unknown to a typical OT-2 Jupyter Notebook user.

Expected behavior

• When it's safe to ignore this warning, its content and visual language should suggest that it's safe to ignore.
  • If it's only safely ignorable under certain circumstances, it should either explain that, or only appear under those conditions.
• The message should be understandable to typical OT-2 Jupyter Notebook users.

[SyntaxColoring]

This message was introduced in #6091. I haven't looked at the code, but I assume part of what makes this hard is that this isn't specifically a Jupyter Notebook message. It's a message to warn of a certain technical condition, and doing opentrons.execute.get_protocol_api() from Jupyter Notebook just so happens to run into that technical condition.

It might be hard for the message be user-friendly enough for Jupyter Notebook, while simultaneously being specific and technical enough for the other circumstances in which it can appear. I'm not sure.

[SyntaxColoring]

Personal opinion: this message should be contextual. We should strive to not show warnings that burden the user with figuring out whether they apply to their circumstances.

Instead, the message could appear only if you actually try to set_rail_lights() (and wherever else it matters). The majority of users—for whom this message never applied—will stop seeing it.

Others have disagreed with this. I think their case against making this message contextual is that we don't want to spring surprise limitations on users when they're already halfway through writing their code. If there's a limitation, we should be up-front with it.

My response is that, yes, up-front warnings are good—but Jupyter Notebook output isn't a good place for them. Up-front warnings should instead be in the docs, where we have the space and formatting capabilities to explain them better.

Anyway, making this message contextual is orthogonal to changing its wording. I think we should look into changing its wording, regardless.