Sorry for top-posting, but I'm making a general response rather than to
individual points.
So, I don't think it'd be that hard for congruity to support any of the
API designs below, including different paths for different remote
architectures all determined at run-time.
However, I'd prefer a single unified API.
My reasoning is this: congruity/concordance's purpose is to provide a
pretty UI over libconcord, and not to implement knowledge of how to
program the different remotes; such abstraction (whether it be a unified
API, or even just a database that maps from arch to a list of required
operations by the UI application) belongs in libconcord, since that's
where all other knowledge re: remote programming is.
From my perspective, I think the perfect API would be a single
top-level API to do each of:
1) Identify/parse any update/... file
1a) A function to load/parse/... the file
1b) Function(s) to query any information about the parsed file (e.g.
what type of operation is being performed, so this information can be
presented to the user)
1c) Function(s) to query the number and type of steps required to
implement the operation.
2) A single function to perform the entire operation (or perhaps a
single function per type of operation)
This would completely internalize all knowledge of file-formats,
operations, which remotes exist, set of steps required to implement the
operations, etc.
The callback from step 2 would need to be enhanced to include a step ID
as well as percentage or byte-count, in order to match with the data
returned by function(s) in 1c above.
I propose this also because I see that some of the operations have XML
files that can (and do) list multiple "regions" to be updated. Thus, the
set of operations to be executed is not only driven by remote
architecture, but also by update/... file content.
Currently, the API is structured to only handle a single contiguous
region that must be erased and written. With the above API, any changes
to support N regions would be entirely internal to libconcord, and an
application would simply see extra entries in the step list; something
at least congruity could easily adapt to.
Perhaps something like what's below (names need more though; this is
just a rough outline):
struct ParsedOperationFile
enum OperationType
Connectivity
UpdateConfiguration
UpdateFirmware
LearnIR
enum StepType
InitialWebPing
PrepareForUpdate
EraseRegion
WriteRegion
VerifyRegion
FinalizeUpdate
Reset
ReconnectToRemote
SetTime // e.g. yes for 880 no for 700
FinalWebPing
...
enum StepStatus
Starting
Executing
Complete_Success
Failure
Status Callback(ParsedOperationFile *pof, void *cbcontext,
uint32 step, StepStatus step_status,
uint complete_count, uint target_count)
ParsedOperationFile *load_file(char *filename)
void destroy_file(ParsedOperationFile *pof)
OperationType pof_type(ParsedOperationFile *pof)
uint pof_step_count(ParsedOperationFile *pof)
StepType pof_step_type(ParsedOperationFile *pof, uint step)
// e.g. region ID for erase/write/verify, which can be added
// to (or interpolated into printf-style) step labels in the UI
??? pof_step_parameters(ParsedOperationFile *pof, uint step,
// ???:
enum parameter_type, uint parameter_id)
// or update_config_execute, update_firmware_execute, ...?
Status pof_execute(ParsedOperationFile *pof, Callback *cb,
void *context)
? pof_get_failure_information(ParsedOperationFile *pof, ...?)
congruity would use pof_step_* to create the UI widgets when entering
e.g. the "update configuration" page, then whenever a callback was
executed, map from step number to UI widget, and update the percentage
completion bar.
Perhaps extra APIs to determine if a step's completion level is Kb,
percent, ... Perhaps pof_step_parameters would return both data that
forms part of a UI label for the step, and other metadata like this? Or,
perhaps have specific functions for specific step types.
The callback could return Continue/Abort to allow implementation of a
cancel button in a UI.
How does that sound?
On 08/26/2010 12:50 PM, Phil Dibowitz wrote:
> OK all,
>
> [ Stephen, as the primary user of the libconcord API, I'm particularly
>looking for input here from you ]
>
>
> I now have fully functioning 89x support for config updates, connectivity
> tests, and web communication. (No work yet on firmware or learn-ir).
>
> The current libconcord API was designed very much around the HID remotes,
> and so a config update in 0.22 looks like:
>
>prep_config()
>invalidate_flash()
>erase_config()
>write_config_to_remote()
>verify_remote_config()
>finish_config()
>reset_remote()
>[... reconnect]
>set_time()
>
> The ZWave remotes don't expose the low levels that the HID remotes do.
> There's no flash addresses to worry about, or even manual invalidation and
> erasing. It looks like this:
>
> wr
