kbanks
05-16-2008, 06:23 PM
A user has pointed out that we need more documentation on the SNAPpy built-in function vmStat().
This will be addressed in the upcoming 2.1 release of the documentation, but in the meantime here is a preview:
vmStat('statusCode', 'args...')
This function was originally only intended for internal use from Portal. Now that we also support a gateway interface, users are starting to invoke the function directly, and need to know what the supported parameters are.
'statusCode' controls what actions will be taken, and what data will be returned (via a tellVmStat() callback).
The possible statusCode values are:
0 = VM_RESET: stop the SNAPpy Virtual Machine (for script uploading)
1 = VM_IMG_ERASE: erase the current SNAPpy script
2 = VM_WR_BLK: used when uploading scripts - DO NOT CALL THIS!
3 = VM_INIT: restart the SNAPpy Virtual Machine (after script uploading)
4 = VM_NVREAD: read the specified NV Parameter
5 = VM_INFO: returns Image Name (script name) and Link Quality
6 = VM_VERSION: returns software version number
7 = VM_NET: returns Network ID and Channel
8 = VM_SPACE: returns Total Image (script) Space Available
You probably should not be invoking vmStat() with statusCodes of 0-3.
statusCodes 4-8 are safe to call.
After the statusCode, the next argument varies (depending on the statusCode).
After the "varying" argument comes a final optional argument that specifies a "time window" to randomly reply within (more about this below).
For VM_NVREAD, the second argument is the ID of the NV Parameter you want to read (these are the same IDs used in the saveNvParam() and loadNvParam() functions). You can also optionally specify a "reply window".
The reported values will be a "hiByte" of the NV Parameter ID, and a "data" of the actual NV Parameter value.
For VM_INFO, the only parameter is the optional reply window.
The reported values will be a "hiByte" of the current Link Quality, and a "data" of the currently loaded script name (a string).
For VM_VERSION, the only parameter is the optional reply window.
The reported "data" value will be a version number string
For VM_NET, the only parameter is the optional reply window.
The reported values will be a "hiByte" containing the currently active channel (0-15), and a "data" value of the current Network ID
For VM_SPACE, the only parameter is the optional reply window.
The reported "data" value will be the Total Image (script) Space Available
Return value format:
All of the VM_xxx functions invoke a callback named
tellVmStat(word, data)
The least significant byte of word will be the statusCode. The most significant byte will vary depending on the statusCode, and is the "hiByte" described above. The data value is the main return value, and is also dependant on the statusCode.
Return value timing:
If you do not specify a "timewindow" parameter, the nodes will respond immediately.
Some of these commands are multicast by Portal, and we needed a way to keep all of the nodes from trying to respond at once.
Specifying a non-zero "time window" tells the node to pick a random time within the next "time window" seconds, and wait until then to reply.
This will be addressed in the upcoming 2.1 release of the documentation, but in the meantime here is a preview:
vmStat('statusCode', 'args...')
This function was originally only intended for internal use from Portal. Now that we also support a gateway interface, users are starting to invoke the function directly, and need to know what the supported parameters are.
'statusCode' controls what actions will be taken, and what data will be returned (via a tellVmStat() callback).
The possible statusCode values are:
0 = VM_RESET: stop the SNAPpy Virtual Machine (for script uploading)
1 = VM_IMG_ERASE: erase the current SNAPpy script
2 = VM_WR_BLK: used when uploading scripts - DO NOT CALL THIS!
3 = VM_INIT: restart the SNAPpy Virtual Machine (after script uploading)
4 = VM_NVREAD: read the specified NV Parameter
5 = VM_INFO: returns Image Name (script name) and Link Quality
6 = VM_VERSION: returns software version number
7 = VM_NET: returns Network ID and Channel
8 = VM_SPACE: returns Total Image (script) Space Available
You probably should not be invoking vmStat() with statusCodes of 0-3.
statusCodes 4-8 are safe to call.
After the statusCode, the next argument varies (depending on the statusCode).
After the "varying" argument comes a final optional argument that specifies a "time window" to randomly reply within (more about this below).
For VM_NVREAD, the second argument is the ID of the NV Parameter you want to read (these are the same IDs used in the saveNvParam() and loadNvParam() functions). You can also optionally specify a "reply window".
The reported values will be a "hiByte" of the NV Parameter ID, and a "data" of the actual NV Parameter value.
For VM_INFO, the only parameter is the optional reply window.
The reported values will be a "hiByte" of the current Link Quality, and a "data" of the currently loaded script name (a string).
For VM_VERSION, the only parameter is the optional reply window.
The reported "data" value will be a version number string
For VM_NET, the only parameter is the optional reply window.
The reported values will be a "hiByte" containing the currently active channel (0-15), and a "data" value of the current Network ID
For VM_SPACE, the only parameter is the optional reply window.
The reported "data" value will be the Total Image (script) Space Available
Return value format:
All of the VM_xxx functions invoke a callback named
tellVmStat(word, data)
The least significant byte of word will be the statusCode. The most significant byte will vary depending on the statusCode, and is the "hiByte" described above. The data value is the main return value, and is also dependant on the statusCode.
Return value timing:
If you do not specify a "timewindow" parameter, the nodes will respond immediately.
Some of these commands are multicast by Portal, and we needed a way to keep all of the nodes from trying to respond at once.
Specifying a non-zero "time window" tells the node to pick a random time within the next "time window" seconds, and wait until then to reply.