# buzzer module
| Status | Last Update | API Version |
| ------ | ------ | ------ |
| Active | 2020-1-7 | V1.00.00 |
## Description

This provides access to on-board buzzer.



## sysSound

You should use system sound if it is possible.

This table enumerates system sounds:

| Name              | Usage                                                |
| ----------------- | ---------------------------------------------------- |
| sysSound.alarm    | This is specified when an error or warning happened. |
| sysSound.hint     | This is specified when a notification happened.      |
| sysSound.started  | This is specified when an operation is started.      |
| sysSound.finished | This is specified when an operation is finished.     |



## buzzer.system()

### Description
Play a system sound in `sysSound`.

### Parameters
| Name | Type | Range | Usage |
| ------ | ------ | ------ |  ------ |
| <Sound> | `sysSound` |       |Specify the sound to be played.|
| [WaitForEnd] | boolean |       |Optional. If it is true, the function returns after the sound ended. If it is false, the function returns immediately. If not specified, the function returns immediately.|
### Return value
nil
### Example call
```lua
buzzer.system(sysSound.alarm) --without block
delay.ms(1000)
buzzer.system(sysSound.started,true) --with block 
```


## buzzer.singleTone()

### Description
Play a sound with specified frequency and duration.

### Parameters
| Name | Type | Range | Usage |
| ------ | ------ | ------ |  ------ |
| <Frequency> | number| 100-10000 |Specify the frequency in hertz|
| [Duration] | number | 1-65535 |Specify the duration in miliseconds, if not specified, the tone plays forever.|
| [WaitForEnd] | boolean |  |Optional. If it is true, the function returns after the sound ended. If it is false, the function returns immediately. If not specified, the function returns immediately.|
### Return value
nil
### Example call
```lua
buzzer.singleTone(1000,1000) --1000HZ for 1000ms, non-blocking
buzzer.singleTone(1000,1000,true) --1000HZ for 1000ms, blocking
```



## buzzer.waitForEnd()

### Description

Wait for the sound playing at present to end.

This function returns immediately if no sound is playing.

### Parameters

nil

### Return value

nil

### Example call

```lua
buzzer.singleTone(1000,1000) --1000HZ for 1000ms, non-blocking
buzzer.waitForEnd() --Wait for last sound to be played.
```



## buzzer.stop()

### Description

Stop the sound playing at present.

This function returns immediately if no sound is playing.

### Parameters

nil

### Return value

nil

### Example call

```lua
buzzer.singleTone(1000,1000) --1000HZ for 1000ms, non-blocking
delay.ms(200)
buzzer.stop() --Stop the sound, the sound should be played for only 200 miliseconds.
```



## Example Code

```lua
--[[This is a demo for buzzer APIs.
    See comments to understand well.

    Detailed Documentation:
    Version: 20200117
    Author:  yanke928
]]

buzzer.system(sysSound.alarm) --Non-blocking
buzzer.waitForEnd() --Wait for end

delay.ms(1000)

buzzer.system(sysSound.alarm,true) --Blocking

delay.ms(1000)

buzzer.singleTone(1000,1000) --1000HZ for 1000ms, Non-blocking
buzzer.waitForEnd() --Wait for end

delay.ms(1000)

buzzer.singleTone(1000,1000,true) --1000HZ for 1000ms, blocking

delay.ms(1000)

buzzer.singleTone(1000,1000) --1000HZ for 1000ms, non-blocking
delay.ms(200)
buzzer.stop() --Stop the sound, the sound should be played for only 200ms

os.exit(0)
```