[Feature] System flag to indicate first execution of program

[gyenesvi]

As discussed in another topic (#1476), a program is not really able to tell if the contents of the persistent storage are valid for the given program or not, because new programs are possible to install without clearing the storage, which makes it hard to use it safely (the only workable solution we came to was using program-specific magic ids written into the beginning of the storage, which is cumbersome to maintain across programs).

I'd propose a system flag to indicate whether the current program being run is the first run of the program. I imagine this flag could always be set when a program is downloaded to the hub, and cleared automatically upon program termination. (I'm not sure if any hub can store more than one programs, then this would have to be a separate flag per program.)

This could be a better alternative to clearing the persistent storage itself, which may not always be desirable, and would require a new UI component. This solution would not effect existing programs as the flag could simply be omitted. However, programs that wish to observe the flag may choose to clear or initialize the storage with valid contents themselves (or even do any other one-time actions, such as showing usage tips on a hub with display).

I imagine it could be accessed like hub.system.is_first_execution (if only one program is ever possible on a hub).

Is this technically possible (setting and clearing such a flag automatically as proposed)?

[laurensvalk]

This could be useful indeed.

When we are adding this, we could also add a way to test being connected to the computer or not. This has been requested a few times as well.

[laurensvalk]

I'd propose a system flag to indicate whether the current program being run is the first run of the program. I imagine this flag could always be set when a program is downloaded to the hub, and cleared automatically upon program termination.

Even simpler, and essentially equivalent, is to set a flag indicating whether the program was started from the IDE, or with the button on the hub.

When we are adding this, we could also add a way to test being connected to the computer or not. This has been requested a few times as well.

If there are a few more useful indicators, maybe we can have a single hub.system.status dictionary with each of these.

Or just expose the existing status bit flags. (Although "started with button" is not an available status right now.)

[laurensvalk]

The reset_reason and name that we currently have in system could belong in such a system.info dictionary quite well too. Then we wouldn't need new methods each time we add something. (We can keep name and reset_reason for backwards compatibility)

So the candidates we have are:

print(hub.system.info())
{
    'name': 'test',
    'reset_reason': 0,
    'ble_host_connected': True,
    'program_started_with_button': True,
    'program_id': 2,
    # program_size (?)
    # mac_address (?)
    # free_space (?)
    # uptime (?)
    # program_run_count (?) (since boot, not persistent)
}

[gyenesvi]

Looks good to me.

Even simpler, and essentially equivalent, is to set a flag indicating whether the program was started from the IDE, or with the button on the hub.

Yes, that sounds like almost the same thing, I guess when one starts the program from the IDE, it is being edited and updated anyway.

[laurensvalk]

print(hub.system.info())

Output for program started with button:

{'program_start_type': 2, 'host_connected_ble': True, 'name': 'prime_hub', 'reset_reason': 1}

When started with Pybricks Code:

{'program_start_type': 3, 'host_connected_ble': True, 'name': 'prime_hub', 'reset_reason': 1}

The numeric codes (2 or 3) will be documented in the API docs.

[gyenesvi]

Thanks for implementing this! One note, would it be possible to have the possible values as enums/constants? Would make the program more readable. Are there any other values than 2 and 3?

[laurensvalk]

The numeric codes will be documented in the API docs. Since this is a fairly advanced use case, I think it's OK to ask users to find a number in the documentation. Just like reset_reason, also in this info dictionary. The Python enum-like objects are fairly big in terms of size, so we've only used them for very commonly used ones like Port.

[gyenesvi]

I see, in that case I guess my best option is to define constants in the beginning of my program to make it more readable? Aren't there system defined constants?

[laurensvalk]

Right. You could use micropython.const.