Contributing to the Sensor Library

#1

In the recent discussion about new features @ahmetus suggested it would be useful to have a draft style guide for submitting sensor interfaces for inclusion in the uLisp Sensor Library. Comments welcomed.

Scope

My belief is that the interface routines should be designed to be as simple as possible, adopting default settings to keep the functions short.

Where there are additional settings, these should be provided by a separate optional function, rather than making the main function try and cater for everything.

Naming

Each function should be named with a short version of the sensor part number, followed by -init for the initialisation function, -temp for the temperature function, and so on.

So the functions for the Si7021 Humidity Sensor would be named:

si7021-init, si7021-temp, and si7021-humidity.

This naming convention is designed so you can have multiple sensors installed at once without conflict, even if more than one provides a temperature reading, for example.

Integer or floating-point?

Where possible the routines should be designed to use integer arithmetic, so they can be run on 8/16-bit platforms. For example, this routine for the ADT7410 returns the temperature in sixteenths of a degree:

(defun adt7410-temp ()
  (with-i2c (str #x48) 
    (write-byte 0 str)
    (restart-i2c str 2)
    (let* ((hi (read-byte str))
           (lo (read-byte str))
           (tmp (logior (ash hi 5) (ash lo -3))))
      (- (logand tmp #x0FFF) (logand tmp #x1000)))))

A user who wants the temperature as a floating-point number, in Ā°C, can do:

(/ (adt7410-temp) 16)

Sample output

An example of sample output from the routine should be shown; for example:

> (adt7410-temp)
338

shows that the temperature is 21.125Ā°C.

I accept that many of the functions already in the sensor library donā€™t keep to these conventions, and Iā€™ll update them in due course.

Currently thereā€™s no way for users to upload new sensors to the library, but if you post them on the forum in this Sensor Library category Iā€™ll add them to the library.

What new features would you like to see in uLisp?
#2

Thanks for your consideration. I have no objection except si7021-humidity; it would be better if it named like si7021-hum :)

If most used ones could be added to ulisp, then we can have a great prototyping tool for all purposes. Iā€™ll try to support your effort, at least I can do demo(Iā€™ll be better-Iā€™m learning this), and maybe written tutorial.

Interface seems reasonable. All we need is adapting Adafruit Sensors. I feel like neopixel led and all OLED display drivers should come first. Also E-Paper drivers are important too. Other than that, some most used and dirt chip chinese copies available sensors I know :

Here is the list of all of them that circuitpython supports, which means these are the generally used, you may find that circuitpython implementations is interesting, maybe it could be helpful for interfacing names too :

https://circuitpython.readthedocs.io/projects/bundle/en/latest/drivers.html

Audio Helpers

Music, noisemakers, and more.

Blinky

Multi-color LED drivers.

Displays

Drivers used to display information. Either pixel or segment based.

Pixel based displays are implemented in two different ways. The original method called ā€œframebufā€ uses a traditional frame buffer model where all pixels are stored in the microcontrollerā€™s ram. The newer method called ā€œdisplayioā€ generates the pixels on the fly and relies on the displayā€™s ram to store the final pixels. ā€œdisplayioā€ drivers will also work with CircuitPython to display error messages and other output to the display when the user code is not using it.

The ā€œdisplayioā€ drivers are recommended.

Color TFT-LCD

OLED

E-Paper / E-Ink

Other

Real-time clocks

Chips that keep current calendar time with a backup battery. The current date and time is available through datetime .

Motion Sensors

Motion relating sensing including acceleration , magnetic , gyro , and orientation .

Environmental Sensors

Sense attributes of the environment including temperature , relative_humidity , pressure , equivalent carbon dioxide ( eco2 / eCO2 ), and total volatile organic compounds ( tvoc / TVOC ).

Light Sensors

These sensors detect light related attributes such as color , light (unit-less), and lux (light in SI lux).

Distance Sensors

These sensors measure the distance to another object and may also measure light level ( light and lux ).

Radio

These chips communicate to others over radio.

IO Expansion

These provide functionality similar to analogio , digitalio , pulseio , and touchio .

Miscellaneous

#3

@ahmetus thanks for the comprehensive list. A bit daunting, but something to aim for!

I have no objection except si7021-humidity; it would be better if it named like si7021-hum :)

Hmm Iā€™m not sure about that; ā€˜tempā€™ is an obvious abbreviation for temperature, but ā€˜humā€™ isnā€™t quite so intuitive, and nor is ā€˜pressā€™, so I think we should keep those in full.

#4

Maybe ā€œhumdā€ or ā€œhumdtā€ thenā€¦

#5

There may be a culture clash here. Apart from some historically-determined names, Lisp has a tendency to use function and variable names that are much more verbose than is common in other programming languages. There are reasons to be less verbose with uLisp, but once youā€™re into the symbol table anyway those are more or less gone.

#6

Sorry for that, but if you do all of them, youā€™ll be ahead of circuitpython-micropython circus:) Because this is lisp, we have more interactivity in any circumstances, But I can shortened a bit with my priorities :)

  • Bosch Inertial Measurement Unit - BMI160
  • Electret Microphone Amplifier - MAX9814 with Auto Gain Control
#7

Some of these would probably require uLisp functions written in C, rather than being purely written in Lisp like the other functions currently in the Sensor Library.

What do you envisage for the uLisp interface to the microphone amplifier? Would uLisp simply act as a controller, allowing you to start and stop recording to a memory buffer, and then replay that buffer? Or would uLisp record audio into the uLisp workspace so it could be manipulated by a Lisp program; for example, to do a Fast Fourier Transform?

#8

Actually if you guide us as a C programmer - giving a detailed tutorial about how do you write sensor libraries with C for ulisp, defining some conventions for us, maybe we can be more helpful. Iā€™m average programmer, some 7 - 8 language in my belt, and not a master none of them. Iā€™m coming from web and mobil background. But Lisp was one of my first loves, I learned programming with Touretzkyā€™s Gentle Introduction, and I have maybe fifteen Lisp books, still Iā€™m not a macro or library writer, but Iā€™m resourceful if Iā€™m in. Always.

Iā€™m also new in embeding space, other background I have is native mobil ios - android development.

Iā€™m entuhastist because I loved Arduino and the other things comes with it because itā€™s so simple than mobil development. I know it hides behind enormous complexity, but eventually it is C, knowing and learning tricks should lead to progress, I hope it anyway.

Both ways do the job for me, most powerful chips like k210 and nRF52840 have Audio and FFT chips onboard, how we can use this? Iā€™m prefer if we can use this chips for encoding and decoding powers. HAL is the key I suppose, not that I know much, again.

I have time, hope we can work togetherā€¦

#9

Would that be for performance reasons? I donā€™t think thereā€™s any protocols involved that arenā€™t supported.

#10

I was thinking for example of video or audio capture; I donā€™t think uLisp would be fast enough.

#11

It can be fast enough with your ARM assembly and array support. Not for all devices, but k210 and nRF52840 definitely capable enough, and had plenty of ram. I think esp32-wrover module with extra psram also will be powerful enough.

#12

I tested when I first run this on Maix bit; FFT Spectrum Analyses :

It uses onboard fft chip. I played Tangerine Dream Central Park, Spectrum was awesome! I didnā€™t record that in that time, Iā€™m hoping I can do this with ulisp, if you ask, Iā€™ll do again and record.

#13

Hmm, yeah, ā€œhumidityā€ is pretty long to type and fit on the small screens uLisp works on.

That said, one of the things I like about Lisp is the convention of not using short forms like the ones youā€™re suggesting, because I find them hard to remember. See https://lisp-lang.org/style-guide/#naming, and ā€œThese will annoy peopleā€ in CLiki.

Maybe the uLisp REPL needs symbol completion support.

Another idea is to define a set of uLisp conventional short forms in a prominent table in the uLisp Language Reference. Then one only needs to memorize that set of short forms, and one can assume complete words for everything else.

#14

I know that and normally it is good tradition. But this is limited subset of Common Lisp as you know, it make sense if little brother uLisp use small names. Because he is little than big brother, and his place is so small. There for this doesnā€™t look weird in that context to me.

I donā€™t expect that until uLisp compiles. Too much resource limit at stake.

I agree, good idea, Emacs can do completion with some simple uLisp mode.

#15

The functions in the Sensor Library are intended as a guide; users can rename them if they want shorter names. I think itā€™s more important that itā€™s clear what each function does from its name.