> For the complete documentation index, see [llms.txt](https://plumgeek.gitbook.io/spirit-rover-code-quick-reference/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://plumgeek.gitbook.io/spirit-rover-code-quick-reference/arduino-code/light-sensors.md).

# Light Sensors

## Light Sensors:

**PIC\_ReadAllAmbientSensors();**\
`PIC_ReadAllAmbientSensors(); //retrieves reading for all 3 ambient light sensors. Accurate to within 20ms ago.`\
Populates the following global variables:\
**ambLeft, ambRight, ambRear**

.

**PIC\_ReadAllSurfaceSensors();**\
`PIC_ReadAllSurfaceSensors(); //retrieves reading for all 6 surface sensors. Accurate to within 20ms ago.`\
Populates the following global variables:\
**surfLeft0, surfLeft1, surfRight0, surfRight1, surfRear0, surfRear1**

.

**PIC\_ReadAllAmbientSensorsInstant();**\
`PIC_ReadAllAmbientSensorsInstant(); //retrieves instant reading for all 3 ambient light sensors.`\
Populates the following global variables:\
**ambLeft, ambRight, ambRear**\
This function pauses PIC for a short moment to take a new instant reading of the sensors and reply with the values. Use this function if an instant reading is really necessary. In most cases, a reading that is between 1ms and 20ms old is okay. In that case, you should generally use the normal function PIC\_ReadAllAmbientSensors instead.

.

**PIC\_ReadAllSurfaceSensorsInstant();**\
`PIC_ReadAllSurfaceSensorsInstant(); //retrieves instant reading for all 6 surface sensors.`\
Populates the following global variables:\
**surfLeft0, surfLeft1, surfRight0, surfRight1, surfRear0, surfRear1**\
This function pauses PIC for a short moment to take a new instant reading of the sensors and reply with the values. Use this function if an instant reading is really necessary. In most cases, a reading that is between 1ms and 20ms old is okay. In that case, you should generally use the normal function PIC\_ReadAllSurfaceSensors instead.

.

**PIC\_ReadAllAmbientAverages();**\
`PIC_ReadAllAmbientAverages(); //retrieves running average for all 3 amb light sensors.`\
Populates the following global variables:\
**ambLeftAverage, ambRightAverage, ambRearAverage**

.

**PIC\_ReadAllSurfaceAverages();**\
`PIC_ReadAllSurfaceAverages(); //retrieves running average for all 6 surface sensors.`\
Populates the following global variables:\
**surfLeft0Average, surfLeft1Average, surfRight0Average, surfRight1Average, surfRear0Average, surfRear1Average**

.

**PIC\_SetAverageIntervals();**\
`PIC_AvgIntervalSurface = 6; //Average surface every 6th 20ms period.`\
`PIC_AvgIntervalAmbient = 6; //Average ambient every 6th 20ms period.`\
`PIC_SetAverageIntervals(); //Sets average intervals to PIC processor.`\
The PIC processor automatically calculates a running average based a given count of 8 previous readings. Set the global variables PIC\_AvgIntervalSurface and PIC\_AvgIntervalAmbient first, then call PIC\_SetAverageIntervals(); to latch the values to PIC processor. A reading will be taken every n'th 20ms period, and averaged in with the previous readings taken at n'th 20ms periods. Setting the interval to a lower level will make the average change more quickly. Values can range from 1 to 255 periods.\
Note: This function also latches the global variable PIC\_AvgIntervalPower at the same time, which controls a similar average for battery voltage and current consumption averages.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://plumgeek.gitbook.io/spirit-rover-code-quick-reference/arduino-code/light-sensors.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.