== ARK Datalogging API ==

An instrument using a Sound Design circuit, which supports datalogging, will generate a CSV file with the log details.  These values can be read independently of whether the instrument has been read or not.
=== Decoding CSV Datalog File ===
The .csv file is a comma delimited file with the following row and column (field) definitions:
  * The datalogging version is stored in the first line of the file (row 1). This row has 1 field. Eg.: ''--Version 1.0--''
  * Short-Term Data consists of 5 fields:
     # Timestamp
     # Battery Level
     # Memory
     # VC Level
     # Ambient Level
     # (2.0 only) iSceneDetect (Environment Classification) Value
  * Long-Term Data is a single line written after the short-term data and consists of the number of cycles spent in each memory. This row has 4 fields in the following format:
     # Total spent in Memory 1
     # Total spent in Memory 2
     # Total spent in Memory 3
     # Total spent in Memory 4
  * (2.0 only) Interval time, calculated with the following formula: (X + 1)*4.096
  * Examples:<code csv>
--Version 1.0--
0,2,0,0,55
0,3,0,0,76
0,3,0,-42.1,55
0,2,1,0,82
0,2,1,0,67
0,3,1,0,82
0,2,1,0,73
0,2,1,0,67
0,2,1,0,61
0,2,2,0,61
2,2,2,0,55
. . .
0,3,0,0,58
0,3,0,0,61
1283,5,1,0
</code><code csv>
--Version 2.0--
0,9,1,-6,55,14
85,9,0,-6,58,0
233,9,3,-6,58,14
248,9,0,-6,67,0
249,9,0,-6,67,2
250,9,0,-6,61,0
2
</code>

5,9,0,-6,58,0
. . .
20,9,0,-6,58,0
21,9,0,-6,55,2
365,246,19,454
6
</code>

=== Field Details ===
For any rows with the exception of the first and last rows, these are the fields:
1. **Timestamp**

 * The timestamp is a value from 0 to 63(v1.0) or 0 to 255(v2.0).  Each increment of the timestamp represents 15 minutes of elapsed time.  
 * At power on, the logging routine will always log a new value with a timestamp of 0 to represent a new session.
 * If the device remains powered on for more than 16 hours, the device will log a timestamp of 63 (even if nothing changed in the part), and the timestamps will start again at 1 (i.e. a timestamp of 0 will be skipped because this value indicates a new session).

2. **Battery Level**

iLog version 2.0 provides more granularity in the battery level

v1.0 settings
 * The battery level is a value from 0 to 3.  
 * 3 = 1.3V or higher
 * 2 = 1.2V to 1.29V
 * 1 = 1.1V to 1.19V
 * 0 = Less than 1.1V

v2.0 settings
 * The battery level is a value from 0 to 15.
 * 15 = 1.468 to 1.502
 * 14 = 1.444 to 1.467
 * 13 = 1.421 to 1.443
 * 12 = 1.397 to 1.420
 * 11 =1.373 to 1.396
 * 10 = 1.350 to 1.372
 * 9 = 1.326 to 1.349
 * 8 = 1.303 to 1.325
 * 7 = 1.279 to 1.302
 * 6 =1.256 to 1.278
 * 5 = 1.232 to 1.255
 * 4 = 1.208 to 1.231
 * 3 = 1.185 to 1.207
 * 2 = 1.156 to 1.184
 * 1 = 1.135 to 1.155
 * 0 = Less than 1.135V


3. **Memory**

 * 0 = memory 1
 * 1 = memory 2
 * 2 = memory 3
 * 3 = memory 4

4. **VC Level**

 * 0 to -47.1 dB

5. **Ambient Level**

 * 55 to 100 dBSPL

6. **iSceneDetect (Environmental Classification) Value**

 *0 = Quiet Mode
 * 2 = Speech In Quiet Mode
 * 4 = Music Mode
 * 8 = Noise Mode
 * 10 = Speech In Noise Mode
 * 14 = Off
 * Odd value = Wind Mode (i.e. 1, 3, 5, 7, 9, 11, 13)

=== Generating a CSV Datalog File ===
<code vb>
Private Declare Function SHGetSpecialFolderLocation _
    Lib "shell32" (ByVal hWnd As Long, _
    ByVal nFolder As Long, ppidl As Long) As Long

Private Declare Function SHGetPathFromIDList _
    Lib "shell32" Alias "SHGetPathFromIDListA" _
    (ByVal Pidl As Long, ByVal pszPath As String) As Long

Private Declare Sub CoTaskMemFree Lib "ole32" (ByVal pvoid As Long)
    
Const CSIDL_APPDATA = &H1A
Const MAX_PATH = 300
Const NOERROR = 0



Private Function SpecFolder(ByVal lngFolder As Long) As String
    Dim lngPidlFound As Long
    Dim lngFolderFound As Long
    Dim lngPidl As Long
    Dim strPath As String

    strPath = Space(MAX_PATH)
    lngPidlFound = SHGetSpecialFolderLocation(0, lngFolder, lngPidl)
    If lngPidlFound = NOERROR Then
        lngFolderFound = SHGetPathFromIDList(lngPidl, strPath)
        If lngFolderFound Then
            SpecFolder = Left$(strPath, _
                InStr(1, strPath, vbNullChar) - 1)
        End If
    End If
    CoTaskMemFree lngPidl
End Function
    
Private Sub ReadDataLog()
    Dim i As Integer
    Dim prg2 As ark.IProgrammer2
    Dim datalog As ark.IDataLog
    Dim datalogentry As ark.IDataLogEntry
    Dim ventprod5 As ark.IVentureProduct5
    Dim freefd As Integer
    Dim memcount() As Long
    Dim lRet As Long
    Dim bRet As Boolean
    Dim FileName As String
    Dim corruptionerror As Boolean
    
    If Not g_Cache(g_CurrentEar).LastOp = OP_INIT Then _
        Err.Raise vbObjectError, , "Device not initialized."

    Set prg2 = g_Prog
    SetMousePointerBusy True
    
    On Error Resume Next
    Set ventprod5 = g_Prod
    On Error GoTo HandleError
    
    If Not ventprod5 Is Nothing Then
        If ventprod5.HybridVal <> 33 Then
            MsgBox "Datalogging is not supported in this product", vbOKOnly, "Error"
            Exit Sub
        End If
    Else
        Exit Sub
    End If
    
    Set datalog = ventprod5.ReadLogSafe(prg2, g_CurrentEar, 4, memcount(), corruptionerror)
    SetMousePointerBusy False
    
    If corruptionerror = True Then
        MsgBox "Warning: Datalog has been corrupted.  Clean data will still be displayed, but time measurements " + _
            "could be inaccurate.", vbOKOnly, "Warning"
    End If
    
    FileName = SpecFolder(CSIDL_APPDATA) + "\Sound Design Technologies\IDS"

    
    'if directory does not exist, create it
    If Dir$(FileName$, vbDirectory) = "" Then
        Shell "cmd /c mkdir " + """" + FileName + """", vbHide
        Sleep 1000 'this sleep is necessary for Vista to allow it to recover from creating the new directory
                    'before it has to go and write a file there.
    End If
    FileName = FileName + "\iLog.csv"
    
    ' Open the output file
    freefd = FreeFile
    Open FileName For Output As freefd
    
    Print #freefd, "--Version 1.0--"
    
    'Write the data to a file
    For i = 0 To datalog.count - 1
         
        Print #freefd, CStr(datalog.Item(i).TimeStamp) + ",";
        Print #freefd, CStr(datalog.Item(i).LogBattLevel) + ",";
        Print #freefd, CStr(datalog.Item(i).LogMemory) + ",";
        Print #freefd, CStr(datalog.Item(i).LogVC) + ",";
        Print #freefd, CStr(datalog.Item(i).LogLEQ)
           
    Next i
    
    For i = 0 To 3
        Print #freefd, CStr(memcount(i));
        If i <> 3 Then
            Print #freefd, ",";
        End If
    Next i
    Print #freefd,
    
    Close freefd
    
    'shell out to DataLogging Display Application
    
    FileName = """" + FileName + """"
    
    bRet = ShellAndWait("iLog.exe" + " " + FileName, 1, lRet, _
    "", App.Path)
    
    If Not bRet Then
        MsgBox "Could not find iLog Application", vbOKOnly
    End If

                    
    Exit Sub
HandleError:
    MsgBox Err.Description, vbOKOnly, "Error"
    SetMousePointerBusy False
End Sub

Private Sub ClearDataLog()
    Dim prg2 As ark.IProgrammer2
    Dim ventprod5 As ark.IVentureProduct5
    
    If Not g_Cache(g_CurrentEar).LastOp = OP_INIT Then _
        Err.Raise vbObjectError, , "Device not initialized."

    Set prg2 = g_Prog

    On Error Resume Next
    Set ventprod5 = g_Prod
    On Error GoTo HandleError
    
    If Not ventprod5 Is Nothing Then
        If ventprod5.HybridVal <> 33 Then
            MsgBox "Datalogging is not supported in this product", vbOKOnly, "Error"
            Exit Sub
        End If
    Else
        Exit Sub
    End If
    
    ventprod5.ResetLog prg2, g_CurrentEar
                    
    Exit Sub
HandleError:
    MsgBox Err.Description, vbOKOnly, "Error"

End Sub

</code>