I thought I'd start a discussion here rather than appending this to an existing ticket. One of the major challenges in developing for the WGM110 is that there is very little documentation on what errors each command might return, and the enumerated errors have no more than a few words of description each. This makes it extremely difficult to build robust applications of non-trivial complexity - there's no way to ensure you've covered even the most important exceptions. A prime example of this is the fact that at least two commands (endpoint send and HTTP response) can return 'buffers_full' responses that must be handled as a retry. This is neither documented nor shown in any examples - the example code doesn't even check for a response.
Everything must be determined by experimentation. Consider cmd_endpoint_close, for example - it's one of the simpler API functions and shouldn't have too many error responses. The documentation only tells you that non-zero means error, and to see the appendix with error codes. The appendix does not associate codes with commands - it just enumerates all possible responses with no context provided.
So what response might cmd_endpoint_close return when trying to close an already-closed socket? At a glance, invalid_param, wrong_state, disconnected, not_found, illegal_value, abort, reset, closed, not_connected, and illegal_argument all seem like possibilities. The correct answer, in this case, is apparently invalid_param.
Now, I'm OK with commands possibly throwing a few generic errors like out_of_memory, unspecified, or hardware as long as there's a note somewhere that they may be returned by any command - they don't necessarily need to be detailed with each command. Each command does need the important responses likely to arise from normal operation - like buffers_full.
It's been three years since I started working with the WGM110 and the documentation has not improved in that time. At this point I have more faith in George RR Martin's new book being finished before anyone gets around to revising the WGM110's API reference.SiLabs is an $860 million/year company. Could a little bit of that maybe go toward having an intern spend a day updating the manual with a few more details on response values?
We are aware that the documentation is not optimal and understand that it might make some customers struggle, especially those building more advanced applications around WGM110.
Currently our resources are focused on other product lines and we are not planning any major improvements on the WGM110 documentation at this stage.
the WGM110 is an active product, not deprecated or anything.
The documentation really needs some fixing and for me the 1.1.1 firmware also cannot be the end of the line.
Please reconsider your decision, because the existing customers, who bought the WGM110 will remember all the issues with this product, when deciding for the next communication module.