Circular buffer

[leewujung]

• [ ] Implement circular buffer (@aidanjohnson)
• [ ] CUnit testing functions in NetBeans (@funnyabc)
• [ ] Benchmark performance (@funnyabc): we currently know latency between single buffers undesirably high (see #17, which is response to the findings from #15)
  • How do you know if you have not dropped samples?
  • How large can the size of each file be before you start to drop samples?

[aidanjohnson]

I started to work on this because it incidentally made implementing multi-channel file writing easier.

• Open source library for circular buffer: https://github.com/wizard97/ArduinoRingBuffer.
• Inspiration: Lua for LabView

[leewujung]

Consider using git submodule since ArduinoRingBuffer is on GitHub also. This is cleaner and helps with long-term maintenance.

Also I think in general if you download code/files directly from somewhere it's better to make them in separate folders so that it is explicit and easier to track and maintain. It's probably more convenient to go with what you have for now so that you don't lost dependencies etc, but at some point (stage 4 maybe) it will be good to organize code from different sources to be in separate folders and as well as additions from this project.

[aidanjohnson]

Benchmark Performance: Testing

Attached is a document outlining areas of concern for testing and measuring performance. See also #7 (testing requirements) @funnyabc: we may need to set more concrete requirements.

~Testing Areas of Concern.pdf~ UPDATE (2018-08-08 11h30): Refer now to https://github.com/aidanjohnson/dt7816/issues/8#issuecomment-411489293

[aidanjohnson]

@funnyabc, here are the steps for connecting and running programs on the board (that I told you verbally) in writing. Let me know if there any unclear or faulty steps.

~Connecting to the DT7816.pdf~

UPDATE (2018-08-01 13h30): Refer now to https://github.com/aidanjohnson/dt7816/wiki/Connecting:-Operation

[aidanjohnson]

@funnyabc, for convenience, I've reproduced the areas of concern pdf in markdown, as well as updated to reflect changes made since then.

---

Testing: Areas of Concern

The following are areas of concern that should be tested. The range in brackets ‘[​file.c​:start-stop]’ correspond to the lines of code in files ​recorder/main.c​ and recorder/recorder_helpers.c​, which are in the directory /opt/ti-sdk-am335x-evm-07.00.00.00/example-applications-dt78xx-examples/, that should be further inspected and tested. These areas of concern are sorted by priority. It can be assumed for now that the dependency libraries (​RingBuf.c​, ​libaiff.c​, and sunriset.c​) function properly. Any bugs in these programs can be addressed as is necessary; they, if any, will crop up as functions in the ​recorder​ program are tested. These areas also apply to the version of the ​recorder​ program as of 2018-08-08 at 10h30.

1. Command line interface cases, that is setting [​main.c​:71-121]: 1.1. Enabled channels

   • [ ] All channels that were to be enabled are enabled (​chan_mask​)
   • [ ] All channels that were to be disabled are disabled (​chan_mask​)

   1.2. Samples per file

   • [ ] Correct change of ​samples_per_file
     
     

   1.3. Clock frequency (sample rate)

   • [ ] Correct change of ​clk.clk_freq
   • [ ] Correct change of ​buffer_object.sample_rate
     
     

   1.4. Sampling duration in days

   • [ ] Correct change of ​duration_days
     
     

   1.5. Number of buffers

   • [ ] Correct change of ​num_buffers
     
     

   1.6. Auto trigger (on by default/off)

   • [ ] Status of the trigger (auto if 0 or default/threshold if 1)
     
     

   1.7. Safety margin

   • [ ] Correct change of ​safety_margin
     
     

   1.8. Night cycling

   • [ ] Sunset and sunrise times not the same if enabled
     
     

   1.9. Latitude

   • [ ] Latitude coordinate set
     
     

   1.10. Longitude

   • [ ] Longitude coordinate set
     
     

   1.11. Command line options

   • [ ] Program exits in error when a flag not of the set ​{s, c, d, b, t, i, m, n, p, l}​ is used
     
     
   2. In general, check that all error checks that result in ​goto _exit​ have expected behaviour. These error checks are:
      • [ ] Sample rate configuration [​main.c​:147-152]
        
        
      • [ ] Trigger configuration [​main.c​:158-166; r​ecorder_helpers.c: configTrig()​]
        
        
      • [ ] Create channel mask [​main.c​:169-173]
        
        
      • [ ] Channel configuration [​main.c​:176-183]
        
        
      • [ ] Initialise AIO structures [​main.c​:186-191]
        
        
      • [ ] Allocation of array buffer dynamic memory [​main.c​:196-204]. That is, check that the buffer dynamically allocated correctly (that is, correct size). (Note that this uses a manufacturer provided function.)
        
        
      • [ ] Allocation of circular buffer dynamic memory [​main.c​:207-212]
        
        
      • [ ] Submission of buffers [​main.c​:253-257]
        
        
      • [ ] Initialisation of ARM [​main.c​:260-264]
        
        
      • [ ] Software start [​main.c​:268-272]
        
        
      • [ ] Status check of active channels [​main.c​:277-283]
        
        
      • [ ] AIFF file creation [​main.c​:291-342]: a. Formatting of file [​main.c​: setMetadata()] b. Opening of file c. Starting of writing d. Sampling writing [​main.c: writeBuffer()​] e. Finishing of writing f. Closing of file
        
        

2. Check that ‘Ctrl+C’ aborts the program at any and all stages. awake at night and asleep during day.

   • [ ] Especially check that during sampling for both when active and inactive; that is awake at night and asleep during day.
     
     

3. Circular buffer (​RingBuf.c​ implementation) [​recorder_helpers.c: writeBuffer()​]; check that:

   • [ ] ‘Read’ pointer that reads the circular buffer and writes to file lags the ‘Write’ pointer that reads from the linear buffer array and writes to the circular buffer by the number of channels; no accidental overwriting
     
     
   • [ ] ‘Write’ makes one cycle after writing all samples per a file
     
     
   • [ ] Cycle continues in the circular path (see ​RingBuf.c​)
     
     
   • [ ] Repeats in one cycle for ​num_buffers​ (per file)
     
     
   • [ ] If ​samples_per_chan * num_buffs * num_channels > 65536​ samples, fatal error occurs [recorder_helpers.c: checkFatal()​]
     
     

4. Day/night (asleep/awake) on/off cycling [​main.c​:226-247]:

   • [ ] Disable ​NIGHT_CYCLE​ to make sure samples (on) regardless of time [​recorder_helpers.h:​90]
     
     
   • [ ] On during time period when ​present​ within (​sunset-safety_margin​) through (​sunrise+safety_margin​) [​recorder_helpers.c: calcSunUpDown()​]
     
     
   • [ ] Off during time period when ​present​ outside (​sunset-safety_margin​) through (​sunrise+safety_margin​) [​recorder_helpers.h: calcSunUpDown()​]
     
     
   • [ ] Updates elapsed day after ​present​ time ahead of ​sunrise ​[​main.c:​346]
     
     

5. Miscellaneous ​recorder_helpers.c​ functions, check that:

   • [ ] ledIndicators()​: If ​status​ is 1 ​&​ ​streaming​ is 1 -> LEDs on (a digital output)
     
     
   • [ ] getTime()​: pres_time​ is equal to time gotten by testing file (within some margin of error)
     
     
   • [ ] getTimeEpoch()​: GMT Unix epoch time returned equal to time gotten (within some margin of error)
     
     
   • [ ] timestamp()​: String is unique
     
     
   • [ ] getPresentTime()​: Same as for ​getTime()
     
     
   • [ ] createChanMask()​: Created channel mask ​chan_mask​ same as that returned by IOCTL_CHAN_GET
     
     
   • [ ] configChan()​: All channels are configured
     
     
   • [ ] initTrig()​: All triggers are configured
     
     
   • [ ] calcSunUpDown()​: Calculated times same as pre-calculated and known times
     
     
   • [ ] writeBuffer()​:
     • [ ] Measure delay/lag time a. Between each channel b. Between loops for saving files c. Scaling with the number of channels being recorded
       
       
     • [ ] Measure time it takes to write file
       
       
     • [ ] Produce complete series of files
       
       
     • [ ] Measure sample drop a. Loss of data b. Scaling with number of channels being recorded
       
       
     • [ ] Write pointer does not overwrite read pointer
       
       
     • [ ] Satisfactory fidelity a. Qualitatively: does recording sound like the test input (from a waveform generator)? b. Objectively: is the spectrum of the recorded waveform sufficiently equivalent to the spectrum of the input? Compare by the threshold the peaks, cross correlation, and/or a self loop analog output to analog input
       
       
   • [ ] checkID()​: Any arbitrary, non-zero length string successful as ID
     
     
   • [ ] checkRate()​: Any arbitrary, positive, non-zero float successful as sampling frequency
     
     
   • [ ] openStream()​: Confirm that opening a real stream is successful, and that opening a bogus stream is a failure
     
     
   • [ ] openAIN()​: Given above, confirm that opening a real analog input is successful, and that opening a bogus analog input is a failure
     
     
   • [ ] waitBuffering()​: No segmentation fault occurs after calling this function, regardless of size of buffer and number of channels
     
     
     • [ ] setMetadata():
       a. Longitude coordinate set as Name attribute b. Latitude coordinate set as Author attribute c. Sunset time (Unix seconds) set as Copyright attribute d. Sunrise time (Unix seconds) set as Annotation attribute